# Alviere Developer Portal The Alviere Developer Portal contains documentation for integrating with the Alviere HIVE platform. It includes platform definitions, integration guides, SDK documentation, webhook guidance, and the HIVE API reference. ## The Alviere HIVE platform HIVE supports the configuration and operation of financial services through Alviere technology and partner integrations. Clients access HIVE through Programs. Each Program contains the modules, configuration, controls, and entities associated with a specific financial-services implementation. ## Core concepts Core concepts explain the modules and entities used within HIVE, including Programs, Accounts, Wallets, Treasury Vault, and money movement flows. ### [Program](https://apidocs.alviere.com/guides/hive-definitions/program) A Program is a configured instance of Alviere modules for a client. A client can operate multiple Programs, each with an independent entity namespace. Data does not cross Program boundaries, including between Programs operated by the same client. Program configuration defines transaction limits, card settings, service fees, KYC and KYB requirements, fraud controls, and compliance rules. Your Alviere Program Manager manages Program configuration. It cannot be changed through the API. ## Integration options Client applications can interact with HIVE through REST APIs or supported SDKs. The available option depends on the application type and the functionality being implemented. ### [The HIVE APIs](https://apidocs.alviere.com/the-hive-apis) The HIVE API reference documents available API operations, request parameters, response objects, and operation-specific requirements. HIVE APIs follow REST conventions and use standard HTTP methods, status codes, and authentication mechanisms. ### [UI SDK](https://websdk.alviere.com/quick-start/overview) `@alviere/ui` is a component library for onboarding and payment flows. It provides forms, multi-step flows, validated inputs, and interface elements. The package includes framework-independent Web Components and typed Svelte components. Both formats expose the same properties and events. UI SDK components use `@alviere/core` for authentication, validation, encryption, and communication with Alviere services. ### [Core SDK](https://websdk.alviere.com/core/overview) `@alviere/core` is the headless logic and data layer used by the UI SDK. It provides typed services for account management, payments, wallets, authentication, request encryption, validation, logging, and error handling. Core does not provide interface components. It can be used when an application supplies its own interface or integrates Alviere functionality into an existing component library or design system. ### [JavaScript SDK](https://apidocs.alviere.com/javascript-sdk) The JavaScript SDK supports browser-based payment, fraud, and card functionality. The client backend creates an authenticated web session. The frontend then loads the SDK using the session identifier and accesses the supported SDK functionality. The documentation covers payment method collection, fraud device data, and card operations such as PIN management. ### [Mobile SDKs](https://alviere.com/mobile-sdks/) The Mobile SDK documentation covers the integration of supported Alviere functionality into native mobile applications. ## Integration guides The integration guides describe the common requirements for connecting an application to HIVE. ### [Integration overview](https://apidocs.alviere.com/guides/integration/overview) The integration overview describes the REST conventions used by HIVE, including URLs, request and response formats, HTTP methods, and status codes. Access to HIVE requires Portal access and authentication credentials. Your Alviere Program Manager provides the credentials associated with your Program. ### [Authentication](https://apidocs.alviere.com/guides/integration/authentication) The authentication guide explains the requirements for authenticating HIVE API requests and using the credentials assigned to your Program. Authentication credentials must be stored securely and must not be exposed in client-side applications. ### [Environments](https://apidocs.alviere.com/guides/integration/environments) Alviere provides separate Sandbox and Production environments, each with its own Portal and API URLs. Use Sandbox to develop and test your integration in an isolated environment. Sandbox does not connect to backend systems, so it does not support KYC or KYB validation, real-money wallet transfers, or bank-account transfers. Production connects to Alviere systems and partners. The functionality available in Production depends on your Program configuration. ### [Webhooks](https://apidocs.alviere.com/guides/webhook/introduction) Use webhooks to receive events from Alviere. For example, when a transaction settles, Alviere sends an event to your webhook consumer with the transaction details. Events are grouped into Subscriptions. When you create a Subscription, you provide the URL where its events should be sent. Alviere sends events asynchronously, so their delivery does not block the operation that produced them. Each event represents an action that has already occurred. ### [Error codes](https://apidocs.alviere.com/guides/integration/error-codes) The error code reference documents errors returned by HIVE APIs and the information included in error responses. Applications should use the HTTP status, error code, and error description to determine how a failed request should be handled. ### [Mock services](https://apidocs.alviere.com/guides/integration/mock-services) Mock services provide documented test scenarios for validating an integration without initiating the corresponding live financial activity. Mock behavior is limited to the scenarios described in the guide and does not reproduce every Production behavior or partner interaction. # Modules and Entities ### Modules Modules in "The HIVE" are clusters of features that collectively offer specific financial services to our clients. Each module is designed to encapsulate a particular area of financial technology, allowing for seamless integration and robust functionality. Here are the current modules we offer: 1. **Accounts**: This module manages all functionalities associated with consumer and business accounts, including account creation, management, and reporting. 2. **Payments**: Focused on facilitating various types of payments and payment processing, this module includes features for card and bank processing, check deposits, p2p transfers and much more. 3. **Branded Cards**: Create, manage, and distribute physical or virtual branded cards (debit, credit, or prepaid) with features like custom branding and real-time transaction monitoring. 4. **Security Risk and Compliance**: This module is dedicated to ensuring that all financial activities comply with relevant laws and regulations. It offers features like Anti-Money Laundering (AML) checks, Know Your Customer (KYC) verifications, and fraud detection. 5. **Global Money Transfers**: Send money globally with various options including currency conversions, international remittance to bank accounts and cash pickup locations, etc. 6. **Portal**: This module serves as the user interface gateway for your employees and administrators alike, providing an integrated experience to manage accounts, view transactions, and access other details about your Program with Alviere. 7. **Business Intelligence & Data**: Focused on data analytics and reporting, this module offers tools for data visualization, trend analysis, and financial reconciliation. By aggregating and analyzing data across your financial program, it aids in making informed decisions and optimizing financial services. ### Entities Entities are the financial objects or components involved in executing any financial service within "The HIVE." Understanding entities will provide you with a granular view of how each module operates. Below are the entities that "The HIVE" manages: | Entity Name | Description | Parent Entity | Example | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------- | | Brand | This represents the company or legal entity utilizing "The HIVE" for their financial services needs. | - | Acme | | Program | An instantiation of modules from the Alviere platform that together provide a set of live financial services to end-customers of a Brand. This includes specific configurations and settings that define how each financial service functions within the context of that Brand. Importantly, all entities, with the exception of "Brand," are unique to a Program and have no relationship to entities contained in other Programs that belong to the same Brand. | Brand | Acme Neobank | | Account | Representation of an end-customer in a program. This could be a Consumer, Business, Stakeholder, or Cardholder account. Each account type offers specific features, limitations and compliance requirements based on its type. | Program | James Smith | | Treasury Vault | Representation of a ledger and underlying bank account that is under the management of the Brand for a specific Program. This serves to support and enable certain fund flows essential for the various financial modules that are part of the Program. | Program | Card funding Prefunding Service fees | | Wallet | A representation of a ledger that captures the transactional activity and available funds of a specific physical or virtual bank account belonging to the end consumer. | Account | Checking Savings Crypto | | Issued Card | Represents a physical, virtual or digital card that has been issued to an end customer, containing features like card numbers, expiry, and additional settings. | Wallet | Debit card Gift card Prepaid card | | Address | A physical location, associated with an entity for different purposes such as validation, contact, shipping, etc. | Account | 1 Alviere Ave New York, NY | | Payment Method | A financial instrument that belongs to the end customer and can be used for either loading funds into a wallet or withdrawing funds from a wallet. Payment methods can be of type card or bank account. | Account | Chase debit card Bank of America bank account | | Beneficiary | An individual or entity external to a Program receiving funds in a financial transaction. | Account | James Jones bic\_code: R133R234XXX | | Transaction | A record that captures the details of any financial operation, such as money transfer, payment, etc. | Wallet | Treasury vault Transaction LOAD\_FUNDS TRANSFER PAYMENT | | Check | An entity that serves as the digital representation of a real-life check, containing detailed information such as the amount, an image of the check, and other relevant particulars. | Wallet | Check | | Dossier | A collection of documents or data that provides detailed information about an end customer or specific transaction. | Account | Passport + Selfie Proof of address | | Payment Instrument | Within the context of payment processing, the tokenized representation of a method used to initiate and complete payments, such as debit cards or bank accounts. | Account | Chase debit card | | Payout Method | A method specifying the channel through which funds will be disbursed to a Beneficiary entity. This could include bank transfers, digital wallets, or other financial instruments tailored for outgoing payments. | Beneficiary | Cash pickup location e-Wallet | | Incentive Rule | A set of guidelines dictating the conditions for applying cashbacks and boost incentives based on merchants and amounts/percentages. | Program | 10% Cashback on all purchases at Amazon | | Quote | Entity designed to offer end customers an estimate of the cost associated with an international transfer. The Quote captures details such as currency exchange rates, fees, and other applicable charges. | Program | 100 USD can be bought for 1730 MXN | Should you have further questions or need additional clarity on these topics, please consult the respective in-depth sections in this developer guide. # Program Within the context of the embedded finance platform, the collaboration between your company (referred to as "Brand") and Alviere is embodied within the system through a designated **Program** account. Your financial offerings can encompass multiple Programs, each housing a distinct array of modules tailored to provide specific financial services to your end customers. Every Program you establish with Alviere contains its own distinct configurations. These configurations, which include a range of options, are exclusively tailored to meet the precise needs of your Program. Alviere extends support for a comprehensive range of program configurations, enabling you to apply specific business rules that cater to your Program's requirements effectively. These program configurations encompass a variety of factors, including but not limited to: * Transaction limits * Customization of cards * Service fees * KYC/KYB prerequisites * Measures for fraud prevention and compliance * And more… It's important to note that each Account is unique to a particular Program. No exchange of data or information occurs between Programs that fall under the same Brand or different Brands. This isolation ensures the integrity and confidentiality of each Program's operations. Configuration settings are managed by your dedicated program manager at Alviere. If you require further insights into your Program's settings, we encourage you to connect with your designated account manager. For a comprehensive understanding of how to effectively utilize and tailor your Program's configurations on the Alviere platform, refer to this developer guide and reach out to your account manager for any additional clarification. # Account **Accounts** represent each individual or business in our platform who is tied to a specific program. The Account entity contains information about the account holder. This information is used to onboard the individual or business prior to being able to access the services being provided. Accounts are created in your onboarding platform using our integration tools (API and/or SDK). Alviere currently supports 4 types of accounts: | Type | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CONSUMER` | This account type is used for individual consumers that are registered in the platform. | | `BUSINESS` | This account type is used for businesses/companies that are registered in the platform. | | `STAKEHOLDER` | This account type is used to represent stakeholders (officers, beneficial owners, etc.) that belong to a Business account. | | `CARDHOLDER` | This account type exists under the umbrella of a Consumer or Business Account and represents an individual that has ownership of an issued card in the system | ### Consumer Account A Consumer Account is a representation of an individual end customer of your program. Consumer Accounts are created and validated in the Alviere platform in stages. Each stage provides different permissions to what actions the Consumer can perform within the Alviere platform. #### Account status The account `status` field indicates the current status of your Consumer Accounts in the Alviere platform. Some statuses are internal and represent the current stage in the identity verification process, while other statuses represent the need to obtain additional information from the customer or that a manual review of the identity is required. Statuses are also used by Account Profiles to represent the verification status of the Profile application. The following statuses are possible for Consumer Accounts in the Alviere platform: | Status | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CREATED` | Prior to KYC and Identity Verification checks, this is the status of an account once you submit a successful account creation request. | | `ACTIVE` | If the Consumer Account is fully active in the system, their status will be `ACTIVE`. Profiles will also become `ACTIVE` when the verification process applicable for the Profile has been completed. | | `INACTIVE` | This status indicates that all permissions to access the system are currently revoked and the Consumer will not be able to perform any actions in the Alviere platform until you choose to reactivate the Account. | | `PROCESSING` | This status indicates that the Profile application is in progress; no action is required while the Consumer is in this status. | | `PENDING_USER` | This status indicates that further action is required from the consumer. This status could occur due to missing or incorrect data on the consumer's profile such as an address or Social Security Number. For more information, see the Status Reasons section below. | | `MANUAL_REVIEW` | This status indicates that the Consumer Account is currently under manual review by an agent. The `stage` property will indicate why the Consumer is under manual review | | `REJECTED` | This status indicates the Consumer Account has been rejected by the platform, either manually or automatically. The reason for the rejection will be returned on the `status_reason` property of the account. | | `DELETED` | This status indicates the Consumer Account has been deleted and removed from the platform. The consumer data will still be present in the system, but the Account cannot be reinstated. If you wish to temporarily remove access to a Consumer, you should change the status to `INACTIVE` instead | #### Processing stage The status of pending verification applies to Consumers that have not yet been completely identified. The possible status reason for the pending verification `stage` property are: | Stage | Description | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FRAUD` | This stage indicates that the fraud check internal process is in progress. | | `ADDRESS` | This stage indicates that the address provided by the Consumer is being validated. | | `IDENTITY` | This stage indicates that the identity verification process is being performed. Information such as the date of birth, address, and/or Social Security Number are being matched against public and platform-private records for accuracy. | | `IDENTITY_OPTIONAL_SSN` | This stage indicates that the identity verification process is being performed with SSN being optional. If no SSN is provided, the identity check still occurs using other profile data. | | `DOCUMENTS` | This stage indicates that the photo identification, provided by the consumer to validate their identity, is being processed. | | `DOCUMENTS_OPTIONAL_FULL_SSN` | This stage indicates that the photo identification is not required if the profile already has the full SSN available and it was successfully verified. | | `SANCTIONS` | This stage indicates that the internal process of Sanctions and Negative News screening is not complete. | | (empty) | This stage indicates that the consumer has not started the KYC validation or is on-boarded and there's no more stages to execute. | #### Status reason The `status_reason` field provides a descriptive reason for the current `status` of the consumer account. | Status Reason | Applicable status(es) | Description | | ---------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `INVALID_NAME` | `PENDING_USER` `MANUAL_REVIEW` | The first and/or last name provided are not valid and one or both need to be re-submitted | | `INVALID_DOB` | `PENDING_USER` `MANUAL_REVIEW` | The provided date of birth is not valid; this could happen for programs where there is a minimum age requirement or the date of birth does not match the public record information on the consumer | | `INVALID_ADDRESS` | `PENDING_USER` `MANUAL_REVIEW` | The consumer has provided an address that is invalid and needs to be re-submitted | | `INVALID_PHONE` | `PENDING_USER` `MANUAL_REVIEW` | The consumer has provided a phone that is invalid and needs to be re-submitted | | `INVALID_LAST_4_SSN` | `PENDING_USER` | The consumer has provided the last 4 digits of their Social Security Number that could not be matched against public and platform-private records. This will generally result in the consumer account being placed in `status_reason: 'REQUIRES_FULL_SSN'`. _Note: This status is only valid for US consumers_ | | `INVALID_SSN` | `PENDING_USER` `MANUAL_REVIEW` | The consumer has provided their Social Security Number that could not be matched against public and platform-private records. This will generally result in the consumer account being placed in `status_reason: 'REQUIRES_FULL_SSN'`. _Note: This status is only valid for US consumers_ | | `REQUIRES_LAST_4_SSN` | `PENDING_USER` | The consumer is required to provide the last 4 digits of their Social Security Number in order to proceed with the identity verification process. This status usually happens when it was not possible to lookup the last 4 digits of their SSN from public records. _Note: This status is only valid for US consumers_ | | `REQUIRES_FULL_SSN` | `PENDING_USER` | The consumer is required to provide their full 9-digit Social Security Number in order to proceed with the identity verification process. This status usually happens when it was not possible to lookup the full SSN from public records. _Note: This status is only valid for US consumers_ | | `INVALID_DOSSIER` | `MANUAL_REVIEW` | The consumer has provided a dossier that is invalid and needs to be re-submitted | | `EXPIRED_DOCUMENT` | `MANUAL_REVIEW` | The consumer has provided a document that is expired. A valid document needs to be submitted to proceed with the identity verification process | | `REQUIRES_DOSSIER` | `PENDING_USER` | KYC/KYB started without dossier/photo identification but did not meet the criteria to continue the onboarding. The consumer now needs to upload photo identification | | `REQUIRES_PASSPORT_RESUBMISSION` | `PENDING_USER` | The consumer has provided a passport document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_ID_DOCUMENT_FRONT_RESUBMISSION` | `PENDING_USER` | The consumer has provided an ID front document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_ID_DOCUMENT_BACK_RESUBMISSION` | `PENDING_USER` | The consumer has provided an ID back document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_DRIVERS_LICENSE_FRONT_RESUBMISSION` | `PENDING_USER` | The consumer has provided a drivers license front document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_DRIVERS_LICENSE_BACK_RESUBMISSION` | `PENDING_USER` | The consumer has provided a drivers license back document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_PROOF_OF_ADDRESS_RESUBMISSION` | `PENDING_USER` | The consumer has provided a proof of address document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_PROOF_OF_FUNDS_RESUBMISSION` | `PENDING_USER` | The consumer has provided a proof of funds document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_MC_DOCUMENT_FRONT_RESUBMISSION` | `PENDING_USER` | The consumer has provided a matricula consular front document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_MC_DOCUMENT_BACK_RESUBMISSION` | `PENDING_USER` | The consumer has provided a matricula consular back document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_CERTIFICATE_OF_INCORPORATION_RESUBMISSION` | `PENDING_USER` | The consumer has provided a certificate of incorporation document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_SELFIE_RESUBMISSION` | `PENDING_USER` | The consumer has provided a selfie which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_INE_FRONT_RESUBMISSION` | `PENDING_USER` | The consumer has provided a INE front document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `REQUIRES_INE_BACK_RESUBMISSION` | `PENDING_USER` | The consumer has provided a INE back document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `COUNTRY_OF_ISSUANCE_MISMATCH` | `PENDING_USER` | Our system detected that the ID provided did not match the country of issuance provided by the consumer as part of the Dossier creation process | | `COUNTRY_OF_ISSUANCE_NOT_SUPPORTED` | `PENDING_USER` | The program does not support the document type and country of issuance provided by the consumer | | `REQUIRES_INE_BACK_RESUBMISSION` | `PENDING_USER` | The consumer has provided a INE back document which needs to be resubmitted as it has not been able to be processed. This is generally the case when the quality of the submitted document is not high enough to be readable | | `TRANSACTION_MANUAL_REVIEW` | `MANUAL_REVIEW` | A consumer initiated transaction was placed in `MANUAL_REVIEW`, triggering the placement of the account into `MANUAL_REVIEW` | | `TRANSACTION_DENY` | `MANUAL_REVIEW` | A consumer initiated transaction was automatically rejected, triggering the placement of the account into `MANUAL_REVIEW` | | `TRANSACTION_RETURNED` | `MANUAL_REVIEW` | Account was put in `MANUAL_REVIEW` because because too many transactions generated returns or chargebacks | | `CHECK_RETURNED` | `MANUAL_REVIEW` | Account was put in `MANUAL_REVIEW` because because too many check deposits were returned by the destination bank | | `STAGE_VALIDATION` | `MANUAL_REVIEW` `REJECTED` | The account was put on this status based on automated decisions performed by our KYC stage validations | | `UNREJECT` | `PROCESSING` | Account that was previously rejected prior to the onboarding process being completed was unrejected and the onboarding process restarts | | `NO_IDENTITY_MATCH` | `REJECTED` | The consumer has failed to provide information to validate their identity. | | `SANCTIONED_USER` | `REJECTED` | The consumer has been positively identified with OFAC Sanctions or Negative News. | | `CONFIRMED_FRAUD`/`FRAUD` | `REJECTED` | Our compliance agents have successfully confirmed the consumer's fraudulent status through verification processes | | `HIGH_RISK_BEHAVIOR` | `REJECTED` | The consumer exhibited high-risk behavior, signifying a significantly elevated likelihood of fraudulent activity | | `FRAUD_ACH_RETURN` | `REJECTED` | An ACH transaction has been returned due to fraud | | `FRAUD_CHECK_RETURN` | `REJECTED` | A transaction using a check has been returned due to fraud | | `FRIENDLY_FRAUD` | `REJECTED` | A transaction has been subject to a customer dispute, wherein the customer alleges non-authorization despite being the actual authorizer | | `ELDER_ABUSE` | `REJECTED` | The account has been compromised by an individual who has gained access to the financial information of an elderly person | | `ID_THEFT` | `REJECTED` | The account has been established or utilized by an individual who has unlawfully obtained someone else's identity | | `ATO_FRAUD` | `REJECTED` | A transaction or an account has been compromised by an unauthorized individual who has obtained access to the customer's login credentials | | `ATO_FRAUD` | `REJECTED` | A transaction or an account has been compromised by an unauthorized individual who has obtained access to the customer's login credentials | | `CUSTOM` | `REJECTED` | The consumer was rejected and the operator has provided a custom description for the rejection | #### List of Occupations The following values are valid as occupations for Consumer accounts: * `ACCOUNTANT` * `ACTOR` * `ADMINISTRATIVE_ASSISTANT` * `ANALYST` * `ARCHITECT` * `ARTIST` * `CARPENTER` * `CASHIER` * `CHILDCARE` * `COOK` * `CLEANER` * `COACH` * `CONSTRUCTION_WORKER` * `CONSULTANT` * `CONTENT_CREATOR` * `COUNSELOR` * `CUSTOMER_SERVICE` * `DATA_ENTRY` * `DESIGNER` * `DENTIST` * `DEVELOPER` * `DIETITIAN` * `DOCTOR` * `DRIVER` * `EDITOR` * `ELECTRICIAN` * `ENGINEER` * `ESTHETICIAN` * `EXECUTIVE` * `EXECUTIVE_ASSISTANT` * `FARMER` * `FINANCIAL_ADVISOR` * `FIREFIGHTER` * `GRAPHIC_DESIGNER` * `HAIRDRESSER` * `HUMAN_RESOURCES` * `IT_SUPPORT` * `JANITOR` * `JUDGE` * `LAWYER` * `LIBRARIAN` * `MAINTENANCE_WORKER` * `MANAGER` * `MEDICAL_ASSISTANT` * `MECHANIC` * `MILITARY` * `MUSICIAN` * `NURSE` * `PARALEGAL` * `PARAMEDIC` * `PHARMACIST` * `PHOTOGRAPHER` * `PHYSICAL_THERAPIST` * `PILOT` * `PLUMBER` * `POLICE_OFFICER` * `POLITICIAN` * `PROJECT_MANAGER` * `PSYCHOLOGIST` * `RECEPTIONIST` * `RESEARCHER` * `RETAIL_ASSOCIATE` * `SALES_REPRESENTATIVE` * `SCIENTIST` * `SECURITY_GUARD` * `SOCIAL_WORKER` * `TEACHER` * `TECHNICIAN` * `TRANSLATOR` * `VETERINARIAN` * `WAREHOUSE_WORKER` * `WELDER` * `WRITER` ### Business Account A Business Account is a representation of an Business or Organization end customer of your program. Just like Consumer Accounts, Business Accounts are created and validated in the Alviere platform in stages. #### Account status The account `status` field indicates the current status of your Business Accounts in the Alviere platform. The following statuses are possible for Business Accounts in the Alviere platform: | Status | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CREATED` | Prior to KYB checks, this is the status of an account once you submit a successful account creation request. | | `ACTIVE` | If the Business Account is fully active in the system, their status will be `ACTIVE`. | | `PROCESSING` | This status indicates that the Business application is in progress; no action is required while the Business is in this status. | | `PENDING_USER` | This status indicates that further action is required from the Business. This status could occur due to missing or incorrect data on the Business's profile. For more information, see the Status Reasons section below. | | `MANUAL_REVIEW` | This status indicates that the Business Account is currently under manual review by an agent. The `stage` property will indicate why the Business is under manual review | | `REJECTED` | This status indicates the Business Account has been rejected by the platform, either manually or automatically. The reason for the rejection will be returned on the `status_reason` property of the account. | | `DELETED` | This status indicates the Business Account has been deleted and removed from the platform. The business data will still be present in the system, but the Account cannot be reinstated. If you wish to temporarily remove access to a Business, you should change the status to `INACTIVE` instead | #### Processing stage The status of pending verification applies to Business that have not yet been completely identified. The possible status reason for the pending verification `stage` property are: | Stage | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SANCTIONS` | We perform a comprehensive sanctions check against the business account to ensure compliance with all relevant regulations. | | `PREVALIDATION` | We validate all submitted information before contacting external providers to ensure its accuracy. | | `VERIFICATION` | In this stage, we thoroughly check all business information for accuracy and authenticity before proceeding with automated processes or stakeholder interactions. | | `DOCUMENTS` | We validate essential business documents to confirm their legitimacy. | | `STAKEHOLDERS` | We identify and validate key business stakeholders, which may include photo ID verification. | | (empty) | This stage indicates that the Business has not started the KYB validation or is on-boarded and there's no more stages to execute. | #### Status reason The `status_reason` field provides a descriptive reason for the current `status` of the consumer account. | Status Reason | Applicable status(es) | Description | | ---------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `ADDRESS_MISMATCH` | `PENDING_USER` | The address information provided does not match official records | | `BUSINESS_NAME_MISMATCH` | `PENDING_USER` | The business name provided does not match official records | | `BUSINESS_TYPE_MISMATCH` | `PENDING_USER` | The business type provided does not align with official records | | `COUNTRY_OF_INCORPORATION_MISMATCH` | `PENDING_USER` | The country of incorporation does not match official records | | `DOING_BUSINESS_AS_MISMATCH` | `PENDING_USER` | The "doing business as" (DBA) name provided does not match official records | | `INVALID_BUSINESS_INFORMATION` | `PENDING_USER` | The business information provided is incorrect or incomplete | | `INVALID_STAKEHOLDER_INFORMATION` | `PENDING_USER` | Provided stakeholder information is incorrect or incomplete | | `INVALID_TAX_ID` | `PENDING_USER` | The tax identification number provided is invalid | | `MISSING_SOURCE_OF_FUNDS_INFORMATION` | `PENDING_USER` | Source of funds information is missing | | `REQUIRES_ACCOUNT_PURPOSE_DETAILS` | `PENDING_USER` | Additional details regarding the account purpose are required | | `REQUIRES_ACCOUNT_PURPOSE` | `PENDING_USER` | The purpose of the account is required | | `REQUIRES_ADDITIONAL_STAKEHOLDERS` | `PENDING_USER` | Additional stakeholders are required for the onboarding process | | `REQUIRES_ARTICLES_OF_INCORPORATION_RESUBMISSION` | `PENDING_USER` | The Business has provided an articles of incorporation document which needs to be resubmitted as it has not been able to be processed | | `REQUIRES_CERTIFICATE_OF_GOOD_STANDING_RESUBMISSION` | `PENDING_USER` | The Business has provided a certificate of good standing document which needs to be resubmitted as it has not been able to be processed | | `REQUIRES_MULTIPLE_DOCUMENTS_RESUBMISSION` | `PENDING_USER` | The Business has provided multiple documents which need to be resubmitted as they has not been able to be processed | | `REQUIRES_MULTIPLE_INFORMATION` | `PENDING_USER` | Multiple pieces of information are required for the registration process | | `REQUIRES_NAICS_CONFIRMATION` | `PENDING_USER` | Confirmation of the NAICS code is required for the registration process | | `REQUIRES_ORG_CHART_RESUBMISSION` | `PENDING_USER` | The Business has provided an org. chart document which needs to be resubmitted as it has not been able to be processed | | `REQUIRES_PHONE_NUMBER` | `PENDING_USER` | A valid phone number is required for the registration process | | `REQUIRES_TRANSACTION_VOLUME` | `PENDING_USER` | Information about the expected transaction volume is required | | `REQUIRES_WEBSITE_ADDRESS` | `PENDING_USER` | A valid website address is required for the registration process | | `STATE_OF_INCORPORATION_MISMATCH` | `PENDING_USER` | The state of incorporation does not match official records | ### Account Profile Account Profiles refer to predefined categories or tiers of Consumer or Business accounts within an Alviere-enabled Program. These profiles enable an organized classification of users based on specific criteria such as the amount of information they provide or the subscription plans they opt for. Each account within the same profile adheres to the same Know Your Customer/Business (KYC/KYB) requirements, ensuring uniformity in the verification process for a specific profile. Upon successful completion of the KYC/KYB process and classification into a specific account profile, end customers gain access to a designated set of modules within the financial program. These modules can include specific features, functionalities, or services tailored to the requirements and privileges of the corresponding profile. By providing varying module access based on profiles, organizations can effectively cater to the diverse needs of their user base. Account Profile assignment is currently primarily based on the extent and depth of personal/business data provided by the Consumer/Business. For instance, a basic profile might only require name, phone number and email, while a more advanced profile might need additional data such as social security numbers, address, etc. In the future, some financial programs may further segment profiles based on the subscription or payment plans users opt for. This criterion allows organizations to align privileges, services, and features with the pricing tiers or benefits associated with each plan. ### Profile setting Programs should select the specific Profile that a Consumer/Business should be created as at Account creation time. If no Profile is set, the Account will be created under the Program's default Profile. The status of the Profile application will be returned as part of the Consumer/Business Account entity `profiles` object, and will contain the following fields: * `profile_name` -> refers to the name of the Profile. Profile names are unique to the Program and are established at Program enablement. * `status` -> refers to the status of the Profile application. Please refer to the _Account status_ section for more details. * `stage` -> refers to the processing stage of the Profile application verification process. Please refer to the _Processing stages_ section for more details. * `status_reason` -> provides a descriptive reason for the current status of the Profile application process. Please refer to the _Processing stages_ section for more details. Once the Profile application process is finished, the Profile status will be `ACTIVE` and the Consumer will obtain the privileges associated with its Profile. ### Profile updating Accounts Profiles can be changed by updating the Consumer/Business account and providing a new Profile setting. Profile updates will only be allowed for Accounts which are in `ACTIVE`, `PENDING_USER` or `CREATED` statuses. The Profile application process will start once all of the required information, including any applicable documentation is uploaded to the Account. Failure to complete the application process will not affect the current status and Profile of the Account (except for situations that trigger a manual review process). If the new Profile default Wallet type is different from the current Profile, a new Wallet will be created automatically for this Account. # Wallet The **Wallet** is a crucial component within the Account entity, designed to manage the transactional activity and funds availability for specific virtual accounts owned by the end consumer. Each Account can have one or more Wallets, offering a space for funds storage and versatile options for transferring and managing money. ### Core Functions A Wallet serves as the ledger that documents transactions and manages the funds that move in and out of accounts. With a Wallet, your customers can accomplish the following tasks: * **Transfer funds**: Move money from one wallet to another within the same or different account holders. * **Bank transfers**: Transfer funds directly from a Wallet to an external bank account. * **Add funds**: Deposit money from an external payment method to a Wallet for funding transactions within your Program. * **Fund Issued Card transactions**: Use the wallet to fund transactions made through cards issued against the account. ### Wallet type There are different types of Wallets to cater to varying financial needs: * `CHECKING`: A flexible wallet designed for everyday transactions. * `PREPAID`: A Wallet you can preload with a set amount for specific spending limits. * `PREPAID_NON_RELOADABLE`: A Wallet that can be loaded once but cannot be reloaded after the initial amount has been spent. * `SAVINGS`: A special type of Wallet designed for long-term fund storage that generates yield over time. * `PASSTHROUGH`: A special type of Wallet used to fund passthrough transactions on Programs that support remittance-only profiles. ### Wallet fund buckets Within the `Wallet` entity, the `funds` object plays a crucial role in detailing the financial state of a wallet. This object comprises several key fields that represent different categories of funds, each with its unique characteristics and implications. Understanding these categories is essential for effective wallet management. #### Available * **Definition**: This field indicates the total amount of funds (in cents) that the consumer is authorized to use. * **Calculation**: * For programs with prefunding: The `available` amount equals the sum of the `balance` and `transit` buckets. * Without prefunding: It is equivalent to the `balance`. #### Balance * **Description**: Represents the settled funds in the wallet, denoted in cents. * **Implication**: Funds in this category are actual and exist in the underlying bank account. They are considered stable and fully processed. ##### Transit * **Nature**: This bucket contains unsettled funds in the wallet, shown in cents. * **Characteristics**: * Typically includes amounts authorized by consumer transactions but not yet settled from the processor. * These funds are counted as `available` as they are prefunded. * The system automatically moves funds from the `transit` bucket to the `balance` bucket upon settlement. ##### Pending * **Context**: Similar to `transit`, it includes unsettled funds in cents. * **Differences**: * Unlike `transit`, these funds are not counted as `available` since they are not prefunded. * The system shifts these funds from `pending` to `balance` once settled. ##### Captive * **Role**: Captive funds denote the amount (in cents) held for transactions executed on the account. * **Example**: * In cases like an ACH Debit on an account, the funds are held in this category until the transaction is executed. * Once settled, funds move to the relevant treasury vault. # Treasury Vault The **Treasury Vault** is a specialized entity residing under the broader Program entity. Acting both as a ledger and an underlying bank account, it is managed by your company for designated Programs. The primary role of the Treasury Vault is to support and enable key fund flows essential for the financial modules that form the Program. Treasury Vaults function as bank accounts tailored for distinct programs. They can facilitate a variety of financial transactions based on the rules of the specific Program. Accessible mainly through Alviere’s Portal under the "Treasury Management" function, these vaults are generally restricted to users with Finance profiles. With the exception of the Master FBO, each Vault type can be linked to specific Payment Methods for loading and withdrawing funds. Though typically these Payment Methods will be bank accounts operating via ACH, credit or debit cards can also be used. ### Treasury Vaults type Here are the various types of Treasury Vaults, each with its own unique set of guidelines: | Vault Type | Functionality | Special Notes | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Card Funding | Specific to Just-In-Time funding, like Gift card programs | Funds belong to your Program and not to the end customers until they are used | | Loss Reserve | Reserve for potential program losses like Chargebacks | N/A | | Service Fees | Holds service fees charged to consumers | Fees can be reversed, transferring back to consumer wallets. | | Prefunding | Provides temporary funds to consumers before settlement | N/A | | Card Settlements | Account where funds from Alviere’s Payment Processor are settled | N/A | | Promo Funds | Holds promotional funds | Cashbacks or Boosts given to customers for card issuance programs will pull funds from this vault | | International Transit | Used in the Global money transfers module for international transactions | When international transactions occur, the funds to fulfill the transaction need to be moved to this vault. | | Operations | Owned by Programs for loading or withdrawing from end customer wallets | N/A | | Providers | This vault is designated for our clients who may wish to separate their funds management from the Operations vault. For instance, clients' providers can directly access funds from this vault, distinguishing it from the Operations vault | N/A | | FX Reserve | Reserve for currency exchange fluctuations | Also handles exchange markups or losses. | # Issued Card The **Issued Card** is a specialized entity that operates as a child of the Wallet entity. It signifies a card, such as a debit or credit card, that is issued to a customer to enable them to make electronic payments and access ATMs. These cards grant the cardholder the ability to access funds in designated bank accounts. They facilitate a wide range of activities including online and in-store purchases, as well as ATM transactions. ### Card type Here are the various types of Issued Cards: | Card Type | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DEBIT` | A card that is directly tied to the funds inside a bank account. Funds are debited immediately upon making a purchase. | | `PREPAID` | Similar to a debit card but not linked to a bank account. Funds are preloaded onto the card and can only spend the amount loaded. | | `PREPAID_NON_RELOADABLE` | A special type of prepaid card that cannot be reloaded once the initial funds are spent. | | `GIFT` | A card preloaded with a specific amount, usually not reloadable. Can be used for online and in-store purchases and is often tied to a specific merchant. | ### Card status Overview The statuses guide you through the card's lifecycle, from its creation to potential expiration or cancellation. Below is a detailed table that outlines the various statuses an Issued Card can have in the Alviere platform. | Status | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------- | | `CREATED` | Initial status when a card is created in the Alviere platform. | | `PENDING` | The card is pending an action from the end customer, such as updating a shipping address | | `PROCESSING` | The card is currently in the processing stage. | | `ACTIVE` | The card is active and can be used for transactions. | | `FROZEN` | The card is frozen; all transaction authorizations will be declined. | | `SET_TO_EMBOSS` | The card is ready to be embossed by the manufacturing partner. This is only applicable to physical card products. | | `READY_TO_ACTIVATE` | The card is ready for activation and PIN setup. This is only applicable to physical card products. | | `RETURNED_MAIL` | The card was returned by the postal service. This status is only applicable to physical card products. | | `LOST_STOLEN` | The card has been reported lost or stolen by the cardholder. This is a final status. | | `CANCELED` | The card has been canceled and can no longer be used. This is a final status. | | `EXPIRED` | The card has reached its expiration date. This is a final status. | # Address The **Address** entity within "The HIVE" platform represents a specific location or point of contact, typically denoting where an individual or business resides or operates. It serves as both a point of communication and a tool for verification, playing a vital role in ensuring accurate identification and secure operations. In the financial realm, the Know Your Customer (KYC) process is crucial, aimed at verifying the identity of an individual or business entity. Within this process, Addresses, particularly the primary one, play a pivotal role. Address validation is mandatory in most KYC configurations, ensuring the platform operates within regulatory guidelines and verifies the legitimacy of the account holder. Every Account in "The HIVE" platform – be it a Consumer, Business, or Cardholder account – is associated with at least one Address. This ensures there's a verified point of contact for diverse purposes, such as mailing checks or notifications. While each account has various Addresses associated with it, one of these is always designated as the 'Primary'. Beyond the primary Address, accounts can have multiple additional Addresses. This allows for flexibility to accommodate various needs – for instance, an individual may want to list both residential and work Addresses. These supplementary Addresses provide versatility, ensuring users can have different locations registered based on their preferences or requirements. # Payment Method The **Payment Method** entity within "The HIVE" platform denotes a financial instrument used by individuals or businesses to manage fund transfers. These instruments facilitate both incoming and outgoing transactions. All **Payment Methods** are tied to an **Account** in "The HIVE", linking each method to either a Consumer, Business, or Cardholder account. This ensures security while offering personalized financial management. Payment methods are versatile, capable of loading and withdrawing from wallets or directly funding transactions like international transfers or P2P activities through passthrough. ### Payment Method type #### Card This widely-accepted method encompasses types such as debit, credit, or prepaid cards, known for their convenience and ubiquity. ##### Card Payment Method status | Status | Description | | ---------- | -------------------------------------------------------------------------------- | | `ACTIVE` | The card is verified and is operational for transactions. | | `FAILED` | An attempt to process the card has failed. | | `EXPIRED` | The card has reached its end-of-life and can't be used for further transactions. | | `REJECTED` | The system has declined the card for use. | | `DELETED` | The card has been removed from the system. | ##### Fail Reasons for Cad Payment Methods To provide clarity on the specific nature reasons why a payment method couldn't be added, the system uses a set of "fail reasons." These reasons aid in diagnosing problems and can guide users or administrators in resolving them. | Fail Reason | Description | | ------------------------------- | ------------------------------------------------------------------------------- | | `CARD_TYPE_NOT_SUPPORTED` | Card payment method type is not supported. | | `CARD_NAME_MISMATCH` | The provided card name and the name registered in the issuer match don't match. | | `CARD_COUNTRY_NOT_ALLOWED` | Card issued by a country that is not allowed in the program. | | `ISSUED_CARD_NOT_ALLOWED_AS_PM` | A card issued by Alviere cannot be used as a payment method. | #### Bank This method connects directly with bank accounts for transactions. Integrations like Plaid simplify the addition of bank-based payment methods, ensuring a seamless, yet secure, experience. ##### Bank Payment Method status In order to provide users with a clear understanding of the state of their bank payment methods, various statuses have been designated. These statuses offer insights into the current functionality or conditions affecting a specific bank payment method. | Status | Description | | ------------ | --------------------------------------------------------- | | `ACTIVE` | The bank account is verified and ready for transactions. | | `PROCESSING` | The bank payment method is currently being verified. | | `FAILED` | A transaction or verification attempt has failed. | | `DELETED` | The bank payment method has been removed from the system. | | `REJECTED` | The bank payment method was declined by the system. | ##### Fail Reasons for Bank Payment Methods Occasionally, bank payment methods may encounter issues that prevent a successful verification. To provide clarity on the specific nature of such setbacks, the system uses a set of "fail reasons." These reasons aid in diagnosing problems and can guide users or administrators in resolving them. | Fail Reason | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------- | | `CUSTOM` | A custom-defined failure reason, possibly specified by administrators or due to unique circumstances. | | `TRANSACTION_FAILED` | The transaction associated with the bank failed due to some issues. | | `NEEDS_UPDATE` | The bank details or method requires an update for successful processing. | | `ACCOUNT_MISMATCH` | The details provided do not match with the bank's records. | | `INVALID_BANK_TYPE` | The type of bank account provided is not supported. | | `INVALID_PUBLIC_TOKEN` | The public token associated with the bank account is not valid. | | `BANK_FAILED` | A verification on the bank account failed, such as the routing number being invalid. | # Transaction ## Definition The **Transaction** entity is a core component of "The HIVE" platform, representing a single financial operation or movement of funds. It captures the essential details of each monetary transaction, ensuring traceability, security, and clarity. ## Transaction scope 1. **Wallet Transactions**: These transactions pertain to the ledger of a wallet. They track the inflow or outflow of funds, reflecting the wallet's activity and balance. 2. **Passthrough Transactions**: These are specialized child transactions designed to fund other parent transactions. Examples include funding international transfers or P2P transfers. They facilitate the seamless movement of funds from a payment method, such as a card or bank account, to fund a higher-level transaction. 3. **Vault Transactions**: These transactions can depict transfers from a wallet to a treasury vault, from a treasury vault to a wallet, or even between a treasury vault and an external bank. Their role is pivotal in adding or removing funds to/from the platform's economy. ## Transaction status The state of a transaction is dynamic, often transitioning through various stages from its initiation to its culmination. Each status offers insights into the transaction's current phase, allowing for better management and oversight. | Status | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `CREATED` | The transaction has been initialized in the system, serving as the inception point. | | `PROCESSING` | At this stage, the transaction is in the midst of processing, typically when a ledger transaction necessitates a payment action. | | `PROCESSING_PAYMENT` | The funds for the transaction are being sourced from a payment method like a card and are currently under processing. | | `COMPLETED` | A successful status indicating the effective transfer of funds. | | `FAILED` | The transaction couldn't process, typically due to payment rejection, like a declined card transaction. | | `ERROR` | A system glitch or anomaly that hindered the transaction's processing. | | `CANCELED_USER` | The transaction was halted either by a customer or an agent via the Portal. | | `CANCELED_SYSTEM` | An automated system rule resulted in the transaction's cancellation. | | `VOIDED` | The transaction was nullified before the actual payment execution, ensuring no debit or credit on the payment method. | | `PENDING` | The transactions is awaiting customer action, or waiting for funds to settle. | | `MANUAL_REVIEW` | This status signifies that the transaction is undergoing a thorough review by Alviere's compliance and risk department. | | `WAITING` | The transaction is on standby, often awaiting the availability of wallet balance funds or inputs from the corresponding prefunding vault. | | `REJECTED` | After manual scrutiny, the transaction was declined by the risk and fraud department. | ## Transaction type Each transaction within "The HIVE" is categorized by a specific type, helping users and administrators understand the purpose and nature of a financial action. The following table provides a detailed breakdown of the available transaction types: | Transaction Type | Description | Wallet | Passthrough | Vault | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- | ----- | | `ACH_PRENOTE` | Zero-dollar test transaction that is sent through the Automated Clearing House (ACH) network. Its purpose is to verify the accuracy of account numbers and routing numbers before initiating actual transactions. | ✓ | - | ✓ | | `ADJUSTMENT` | Transaction initiated by the Operations team to make modifications or corrections in the ledger of a wallet or vault. This action is undertaken to address discrepancies, errors, or to align the ledger with real-world financial activities, ensuring accurate record-keeping and system integrity. | ✓ | - | ✓ | | `BANK_CREDIT` | Transaction type indicating the credit of funds to a wallet resulting from a direct deposit transfer. | ✓ | - | ✓ | | `BANK_DEBIT` | Transaction type indicating the transfer of funds from a wallet to a bank account. This can be via bank transfer to a local Beneficiary or as a result of a direct debit from merchants. | ✓ | - | ✓ | | `CARD_PASSTHROUGH` | Transaction type denoting the direct transfer of funds from a card payment method, bypassing the wallet ledger, to facilitate specific transactions, such as direct bill payments, third-party payments, or international transfers, without affecting the end user's wallet balance. | - | ✓ | ✓ | | `CASH_PASSTHROUGH` | Transaction type denoting the direct transfer of funds from a cash deposit, bypassing the wallet ledger, to facilitate specific transactions, such as direct bill payments, third-party payments, or international transfers, without affecting the end user's wallet balance. | - | ✓ | ✓ | | `BANK_PASSTHROUGH` | Transaction type denoting the direct transfer of funds from a bank payment method, bypassing the wallet ledger, to facilitate specific transactions, such as direct bill payments, third-party payments, or international transfers, without affecting the end user's wallet balance. | - | ✓ | ✓ | | `BOOST` | Transaction type that functions as a discount mechanism during card authorizations. When applied, it enhances the available wallet balance for authorization purposes. | ✓ | - | ✓ | | `CASH_LOADING` | Transaction type indicating the addition of funds into a wallet by depositing physical cash, often through retail partners, kiosks, or other physical cash handling facilities. | ✓ | - | ✓ | | `CASHBACK` | Transaction that signifies a credit given to a wallet as a reward or incentive based on specific purchasing behaviors or promotions. | ✓ | - | ✓ | | `CHARGEBACK` | Transaction initiated when a cardholder disputes a charge, resulting in the funds being debited from the payment processing account and returned to the cardholder. | ✓ | - | ✓ | | `CARD_ISSUED_ADJUSTMENT` | Transaction type related to adjustments or corrections made specifically for transactions or balances associated with a card issued by the platform. This adjustment can be initiated due to various reasons, such as system errors, transaction discrepancies, mischarges, or other irregularities that need alignment to ensure accurate record-keeping and balance integrity for the cardholder's wallet. | ✓ | - | ✓ | | `CARD_ISSUED_ATM_DEBIT` | Transaction that signifies a debit or withdrawal of funds from a cardholder's wallet specifically when the issued card is used at an ATM for cash withdrawal purposes. | ✓ | - | ✓ | | `CARD_ISSUED_CREDIT` | Transaction that represents the crediting of funds to a wallet following an activity or adjustment related to a card issued by the platform. This could be due to reasons such as merchant refunds, or any other credits associated with the card's transactions. | ✓ | - | ✓ | | `CARD_ISSUED_DEBIT` | Transaction that represents a debit from a cardholder's wallet when a purchase or payment is made using the issued card from our platform. This denotes the funds used for regular point-of-sale or online transactions. | ✓ | - | ✓ | | `CARD_ISSUED_DISPUTE_CREDIT` | Transaction type representing a credit adjustment to a cardholder's wallet following the resolution of a dispute in their favor. | ✓ | - | ✓ | | `CARD_ISSUED_DISPUTE_DEBIT` | Transaction type denoting a debit adjustment to a cardholder's wallet due to a dispute resolution that resulted in a chargeback or deduction. | ✓ | - | ✓ | | `CARD_ISSUED_FEE` | Transaction representing a fee that originates externally and applies to a specific transaction conducted with a card issued by the platform. | ✓ | - | ✓ | | `CARD_ISSUED_INITIAL` | Transaction indicating the initial balance added to cards issued by the platform. This type is specifically used for prepaid, prepaid non-reloadable, and gift cards, representing the fund amount that the card is initially loaded with when issued. | ✓ | - | ✓ | | `CARD_ISSUED_OTC_DEBIT` | Transaction type pertains to instances when a cardholder utilizes their card with a human teller at a bank counter, typically to withdraw funds or conduct other card-related transactions. | ✓ | - | ✓ | | `CARD_ISSUED_REISSUE` | Transaction that signifies the reissuance of a gift or prepaid card under the just-in-time funding model. It involves transferring the remaining balance from an expired card to a new one, ensuring continued card usage and balance availability even after the original card's expiration. | ✓ | - | ✓ | | `CARD_ISSUED_RESET` | Transaction that represents the action of resetting the balance of prepaid cards or gift cards when such a card is deemed deleted or has expired. This is particularly relevant for programs operating under the "just in time" funding model, ensuring the funds are effectively managed and accounted for in such scenarios. | ✓ | - | ✓ | | `CARD_ISSUED_TERMINAL_CREDIT` | Transaction type indicating the loading of cash into the wallet associated with a card via a terminal, utilizing networks like Visa ReadyLink and Mastercard Repower. | ✓ | - | ✓ | | `CASHBACK` | Transaction that signifies a credit given to a wallet as a reward or incentive based on specific purchasing behaviors or promotions. | ✓ | - | ✓ | | `CHECK_DEPOSIT` | Transaction type denoting the deposit of funds into a wallet through the submission and clearance of a digital check. | ✓ | - | ✓ | | `CHECK_DEPOSIT_RETURN` | Transaction indicating the return of a deposited check, often due to reasons like insufficient funds or a suspected fraud. | ✓ | - | ✓ | | `CHECK_DISBURSEMENT` | Transaction type representing the distribution of funds from a wallet or vault in the form of a physical or digital check issued to an end-user or another entity. | ✓ | - | ✓ | | `EXTERNAL_CREDIT` | Transaction that denotes the credit of funds into a vault from an external financial source, augmenting the vault's balance. | - | - | ✓ | | `EXTERNAL_DEBIT` | Transaction indicating the debit of funds from a vault, transferring them to an external financial destination, reducing the vault's balance. | - | - | ✓ | | `INTERNAL_CREDIT` | Transaction type indicates the movement of funds internally between different vaults within the platform. | - | - | ✓ | | `INTERNATIONAL_TRANSFER` | Transaction type indicating the movement of funds across borders, enabling your customers to send money to international Beneficiaries. | ✓ | - | ✓ | | `LOAD_FUNDS` | Transaction that pulls funds from a specified payment method (such as a linked bank account or card) and credits them into a wallet within the platform. Typically used to add liquidity or top up a wallet balance. | ✓ | - | ✓ | | `LOAD_PULLBACK` | Transaction initiated by the platform's fraud teams to pull funds from a specified payment method. This action is taken to cover and rectify a wallet's negative balance, ensuring account stability and mitigating potential financial discrepancies. | ✓ | - | ✓ | | `NEGATIVE_LOSS` | Transaction type representing the write-off of a negative wallet balance that cannot be recovered, often due to account closures or unresolved fraudulent activities. | ✓ | - | ✓ | | `PAYMENT` | Transaction type signifies a transaction associated with a merchant's payment processing program. It can either credit or debit funds to the main wallet, depending on the context. | ✓ | - | ✓ | | `PREFUND` | Transaction type that signifies the reverse movement, where funds are credited back to the Master FBO vault from the Prefunding vault. In this case, the Prefunding vault is debited while the Master FBO vault is credited. This mechanism ensures flexibility and fluidity in managing balance funds, allowing for operational efficiency and ensuring that funds are readily available where needed within the platform. | - | - | ✓ | | `RECOVERY` | Transaction that is implemented to reclaim funds from a wallet within the program due to fraudulent activities or suspicious transactions. | ✓ | - | ✓ | | `REFUND` | Transaction type where funds are returned post-transaction, indicating that the initial transaction was processed, and the funds had been debited or credited, but are now being returned to the original source. This is different from a REVERSAL, where the transaction is nullified before any fund movement occurs outside of the platform. | ✓ | - | ✓ | | `RETURN` | Transaction that signifies the reversal of a previous ACH transfer due to reasons such as insufficient funds, closed account, or other reject codes provided by the receiving bank. | ✓ | - | ✓ | | `REFUND_PASSTHROUGH` | Transaction type where funds are returned through a payment method post-transaction. This is specifically for transactions where the initial transaction was processed using a passthrough mechanism, and now the funds are being sent back through the same payment method, essentially reverting the initial fund movement. This maintains the continuity and traceability of funds as they flow back to the original source via the passthrough method. | - | ✓ | ✓ | | `REVERSAL` | Transaction type indicating the reversal of a previously initiated transaction before the funds have left the platform's economy. Unlike a REFUND where funds have been processed and returned post-transaction, in a REVERSAL, the transaction is nullified before any actual fund movement occurs outside of the platform. | ✓ | - | ✓ | | `SERVICE_FEE` | Transaction that debits funds from a user's wallet and transfers them to the service fee treasury vault. This action is taken to cover a service fee that's charged to the end customer for using a specific service or product on the platform. | ✓ | - | ✓ | | `SERVICE_FEE_REVERSAL` | Transaction that credits funds back into a user's wallet from the service fee treasury vault. This is initiated when a previously charged service fee is reversed or refunded to the end customer, typically due to an error, dispute, or promotional activity. | ✓ | - | ✓ | | `TRANSIT_TRANSFER` | Transaction type that denotes an internal movement of funds from the Master FBO vault to the Prefunding vault. This action represents a debit from the Master FBO vault and a subsequent credit to the Prefunding vault. It is utilized to allocate funds that are in transit, ensuring the appropriate categorization and availability of resources within the platform's financial infrastructure. | - | - | ✓ | | `TRANSFER` | A transaction type that denotes the movement of funds from a vault to a wallet, facilitating the funding or replenishing of an individual's or entity's balance from centralized treasury holdings. | ✓ | - | ✓ | | `WALLET_TRANSFER` | Transaction type represents the movement of funds from one wallet to another within the same program. This function is similar to a peer-to-peer (p2p) payment, enabling users to transfer their funds seamlessly to another user's wallet without needing an external intermediary. | ✓ | - | ✓ | | `WITHDRAW_FUNDS` | Transaction that pushes or debits funds from a wallet within the platform and transfers them to a specified payment method (like a bank account or card). This is commonly used to cash out or retrieve funds from a wallet. | ✓ | - | ✓ | # Incentive Incentives are a strategic way to motivate users within a system by providing rewards. Incentives are applied based on rules which are categorized primarily based on the type of incentive they offer: `CASHBACK` and `BOOST` Their application is determined by their scope, which can be either `GLOBAL` or `ISSUED_CARD`. Further, the value of these incentives can be derived from either fixed amounts or percentages of transactions. It's also essential to understand their expiration mechanisms to ensure their effective utilization. ### Incentive type #### Cashback Cashback rules return a portion of the user's expenditure as a reward. It's a popular incentive that promotes spending by promising a rebate on the transaction. #### Boost Boost incentives enhance a user's available balance temporarily. These can be particularly effective for encouraging larger transactions or specific spending behaviors. ### Scope of application #### Global When an incentive rule is marked as `GLOBAL`, it is applicable to every transaction within the system. This broad reach ensures that all users, regardless of their specific details or classifications, receive the benefit. #### Issued Card `ISSUED_CARD` scoped rules are more specific. They are applicable only to transactions made using particular issued cards that the rule is attached to. This allows for targeted incentives, often used to promote a new card or to engage a specific segment of users. ### Calculation base Incentives can be calculated in two primary ways: 1. **Fixed Amounts**: A predetermined sum rewarded to the user, irrespective of the transaction size. For instance, a fixed cashback of $5 on a specific purchase. 2. **Percentage-Based**: The incentive is a fraction of the transaction amount. For example, a 10% cashback would return $10 on a $100 purchase. ### Expiration rules An essential aspect to consider is the duration or usability of an incentive rule: 1. **Date-Based Expiration**: The rule is valid until a predetermined date. After this date, the incentive is no longer available. 2. **Usage-Based Expiration**: The rule expires after being utilized a certain number of times. For example, a user might only be allowed to benefit from a specific cashback three times, after which the incentive is no longer applicable. By leveraging these Incentive Rules, platforms can drive user behaviors, stimulate transactional activity, and ultimately achieve business objectives more effectively. # Beneficiaries and Payout Methods ### Overview **Beneficiaries** and their associated **Payout Methods** play a crucial role in the transaction flow within the platform. This document provides an overview of how Beneficiaries, as well as their Payout Methods (such as bank accounts, cards, electronic wallets, or cash pickup locations), are managed. It covers their association with Account and Program entities, regulatory compliance checks, and statuses. ### Purpose Beneficiaries can have multiple Payout Methods associated with them, meaning that funds can be sent to different accounts or through different mechanisms. For instance, a single Beneficiary may receive funds via direct bank deposit, mobile wallet, card, or a cash pickup location. This flexibility in Payout Methods provides Beneficiaries with diverse options for accessing the funds they receive. ### Entity hierarchy Beneficiaries are established as subordinate entities under Account entities, and Payout Methods entities are further established as children of Beneficiaries, as illustrated below: Account (Consumer, Business) -> Beneficiaries -> Payout Methods ### Beneficiary Beneficiaries serve as the focal point for the end receipt of both international and domestic transactions. A Beneficiary is typically an individual or entity that is designated to receive funds through various transaction types, such as international or domestic transfers. #### Beneficiary creation Beneficiaries are created through the `Create beneficiary`endpoint. When a new Beneficiary is registered on the platform, the system prompts for the submission of personal information related to the recipient. This encompasses particulars such as the Beneficiary's name, the currency for the transaction, and the country where the Beneficiary is officially residing. It is imperative to note that all Beneficiaries are subjected to Sanctions screening, in compliance with regulatory requirements. This screening takes place after a Beneficiary is created and is processed asynchronously within the system. Once all compliance checks have passed, the Beneficiary is placed in the `ACTIVE` status. ##### Best practices for Beneficiary data Transactions involving are subject to validation checks and data quality controls to safeguard against the risks posed by incomplete or inaccurate data. Vague, unclear or partial information in data fields may lead to delays or Rejections in processing Payments. To avoid these, please ensure that all required information and data fields are formatted correctly and accurately. ##### For transactions to individual Beneficiaries, the name must: 1. **Be provided in full**: First Name, Middle Name, Last Name, Second Last Name (if applicable); 2. Between **2-60 characters**; 3. Not contain **special characters** (e.g., !”#$%?:;-\_\*=/); 4. Not contain **company identifiers** (e.g., LLC, LLP); 5. Not contain **initials, acronyms or single character names**; 6. **Do not provide** `and` **in the first or last name field**. The Transaction should be sent to a single person, not multiple people. Examples of High-quality Beneficiary data: * John Smith * John Michael Smith Examples of Low-quality Beneficiary data: * J Smith * John Smith LLP ##### For transactions to **business Beneficiaries**, entity names must: 1. **Have the full legal entity name** without abbreviations except for those of standard suffixes (e.g., LLP, LLC, Ltd.); 2. Follow alphanumeric format **between 2-60 characters**; Examples of High-quality Beneficiary data: * ABC Company Ltd. * X2 Communication Services Limited * Fruits 100 Ltd. Examples of Low-quality Beneficiary data: * 12245678 ##### Beneficiary Address For transactions, the Beneficiary Address should: 1. **Contain the full address**, including the country; 2. **No PO boxes** 3. **Not contain null or missing values**. ### Acceptable Example: * 20 Longleat Drive, Baltimore 12345, Maryland, United States ### Rejected Example: * 12345, Baltimore, Maryland, United States #### Beneficiary update In alignment with compliance protocols, Beneficiaries have the flexibility to update their personal information at any stage, including when their status is `ACTIVE`. This amendment permits the modification of key details such as the beneficiary's `name`, `phone number`, `date of birth`, `label`, and `external_ID`. Following these updates, a re-evaluation for sanctions will be automatically initiated. #### Beneficiary types There are two types of Beneficiaries in the system, `LOCAL`and `INTERNATIONAL`. A `LOCAL` beneficiary is a consumer or business who will receive funds within the same country with the same type of currency (e.g. USD). If the consumer or business are part of the same Alviere Program, they can use P2P, if enabled, to transfer funds - see the `Send funds` API. An `INTERNATIONAL` Beneficiary is an consumer or business who will receive funds outside the sender’s country and it usually involves sending funds in a different currency known as remittance. Note that it is possible for the same consumer to have multiple Beneficiaries in system even though they are the same individual. This scenario would occur when the individual needs to receive funds while `LOCAL` or when abroad making it `INTERNATIONAL`. For example: Jane, who lives in Florida wants to send her daughter, Jennifer, who lives in Texas, some money. In the case, Jennifer would be a `LOCAL` Beneficiary. Now let’s say Jennifer is traveling to Mexico on vacation and needs cash to make a purchase for her mom, Jane. Jane can send Jennifer the funds but she would need to create a new Beneficiary for Jennifer with the type of `INTERNATIONAL` since she in is Mexico. This would also involve a remittance where US dollars are converted to Pesos that Jennifer can pick up at a nearby location to make the purchase. #### Beneficiary statuses Beneficiaries within the platform are assigned statuses that indicate either their position in the validation process or their conclusive status. Below is a comprehensive list of the various statuses that a Beneficiary may be in within the platform: | Status | Description | | --------------- | ------------------------------------------------------------------------------------------ | | `CREATED` | The Beneficiary record has been created and initiated its validation process. | | `ACTIVE` | The beneficiary is active, and funds can be remitted to them. | | `DELETED` | The Beneficiary has been deleted upon the customer's request. This status is irreversible. | | `PROCESSING` | The Beneficiary is undergoing validation for Sanctions screening. | | `PENDING_USER` | The Beneficiary requires the customer to supply additional information. | | `MANUAL_REVIEW` | The Beneficiary is subjected to a manual review by Alviere's compliance department. | | `REJECTED` | The Beneficiary has been rejected by Alviere's compliance department. | The `status_reason` attribute elaborates on the reason for the Beneficiary’s current `status`. It is particularly crucial when additional information or actions are required for moving the Beneficiary through the validation process. The table below summarizes possible values for `status_reason` and their descriptions: | Status Reason | Applicable status(es) | Description | | ------------------ | --------------------- | -------------------------------------------------------------------------------- | | `STAGE_VALIDATION` | `MANUAL_REVIEW` | The compliance validation for the Beneficiary failed, requiring a manual review. | | `INVALID_NAME` | `PENDING_USER` | The provided first and/or last name is invalid, requiring re-submission. | | `SANCTIONED_USER` | `REJECTED` | The Beneficiary has been rejected due to sanctions. | | `CUSTOM` | `REJECTED` | The Beneficiary has been rejected for reasons other than sanctions. | #### Beneficiary address In order to ensure accurate and efficient processing of transactions, it is essential to provide the correct beneficiary address information. The requirements for beneficiary addresses vary by country, encompassing both mandatory and optional fields. Below is a comprehensive table detailing the specific address requirements for countries supported by our platform. This table outlines the character limits and format specifications needed for each field, ensuring compliance with regional regulations and standards. | Country | Line 1 | Line 2 | City | State | Postal code | Country code | | ------------------------ | --------------------------- | ------------------------------- | --------------------------- | ---------------------------- | ------------------------------------ | ------------ | | Argentina | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, ^\[A-Z]?\d{4}\[A-Z]{0,3}$ | ARG | | Bolivia | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, 2-128 characters | not used | BOL | | Brazil | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, 2 letter ISO code | mandatory, ^\[0-9]{5}-\[0-9]{3}$ | BRA | | Chile | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, ^\d{7}$ | CHL | | Colombia | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, ^\d{6}$ | COL | | Ecuador | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, ^\d{6}$ | ECU | | Haiti | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, ^HT\d{4}$ | HTI | | Peru | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, ^\d{5}$ | PER | | Uruguay | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, ^\d{5}$ | URY | | Venezuela | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, ^\d{4}$ | VEN | | Paraguay | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, 2-128 characters | optional, ^\d{6}$ | PRY | | United States of America | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, ^\[A-Z]{2}$ | mandatory, ^.{5,9}$ | USA | | Mexico | mandatory, 2-128 characters | non-mandatory, 2-128 characters | mandatory, 2-128 characters | mandatory, ^\[A-Z]{2-4}$ | mandatory, ^.{5,9}$ | MEX | ### Payout Methods These represent the different options through which the Beneficiaries can receive the funds or resources. Being children of Beneficiaries means that these Payout Methods are associated specifically with each Beneficiary. #### Payout Method types Types of Payout Methods include: **Bank account**: The funds are transferred directly to the Beneficiary's bank account. **Cash pickup location**: The Beneficiary can collect cash in person from a designated location, such as a money transfer service or retail outlet. **Electronic wallet (e-wallet)**: The Beneficiary receives funds in a digital wallet, which can be used for online transactions or converted to physical cash. **Card**: The funds are transferred directly to the bank account that is tied to the Beneficiary's debit card, allowing them to access the funds through their card. **Address**: Custom payout location that is not limited to the platform's supported cash pickup locations. The availability of specific Payout Methods is dependent on the configuration settings of the program they are associated with. #### Payout Method creation The `Create payout method` endpoint, allows for the creation of a new Payout Method within the system. It is mandatory to associate the Payout Method with a specific Beneficiary by supplying the Beneficiary's universally unique identifier (UUID). The Payout Method will be created as a child entity under the designated Beneficiary. In addition a Payout Method can be set as `primary`, meaning that this Payout Method will be the default for this Beneficiary. #### Payout Method update Due to compliance requirements, the account information associated with Payout Methods is immutable once the Payout Method has been created. However, certain non-account-related properties can still be modified. These properties include: * `external_id`: An identifier that can be used for referencing the Payout Method in external systems. * `label`: A human-readable label or description for the Payout Method. * `primary`: A boolean flag indicating whether this Payout Method should be set as the primary/default method for the associated Beneficiary. It is crucial to ensure that the account information is accurate at the time of creation, as it cannot be altered subsequently due to regulatory constraints. The `external_id`, `label`, and `primary` properties offer some flexibility for managing Payout Method metadata and preferences post-creation. #### Payout Method statuses Within the platform, Payout Methods are assigned statuses that provide insights into their current state. These statuses can reflect the Payout Method's position in the validation process or represent a conclusive status that defines its current functionality or state. The table below provides a comprehensive list of the various statuses that a Payout Method can have within the platform: | Status | Description | | --------- | --------------------------------------------------------------------------------------------------------------- | | `ACTIVE` | The Payout Method is in an active state, and funds can be disbursed through it. | | `DELETED` | The Payout Method has been deleted at the request of the customer. This status is final and cannot be reversed. | # Dossier The `Dossier` entity is primarily designed for KYC (Know Your Customer) and KYB (Know Your Business) processes. Additionally, it can be used for tasks such as proof of funds verification. The `Dossier` entity facilitates the collection and verification of critical documentation, enabling the validation of an end user's identity, address, and specific transactions within the Alviere platform. By streamlining the authentication process, it ensures users meet compliance and security standards efficiently. Every Dossier entity is inherently linked to an Account within the system. This intrinsic relationship ensures that each Dossier is always associated with a specific Consumer, Business or Stakeholder Account, thereby maintaining contextual relevance and coherence. ### Dossier Statuses During the lifecycle of a Dossier, it transitions through several statuses. Below is a comprehensive breakdown of each status: | Status | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `CREATED` | Initial status post-submission via the API, indicating Dossier creation. | | `PENDING` | Dossier is currently under verification. | | `MANUAL_REVIEW` | Dossier requires manual verification. | | `VERIFIED` | Dossier approved and consumer identity confirmed. | | `REJECTED` | Dossier denied due to reasons like inauthentic documents or poor photo quality. | | `FAILED` | Dossier verification failed due to invalid document formats. | | `EXPIRED` | Dossier's submitted document has surpassed its valid date. Consumer status reverts to `PENDING_USER` for resubmission of updated documentation. | | `DELETED` | Dossier has been deleted from the system. | ### Documents Within the Dossier entity, the `Documents` object plays a pivotal role. It is an array, where each object represents a specific document that is part of the Dossier. These documents are essential for the identity verification process and can vary in type, each serving a unique purpose in building a comprehensive profile of the user. #### Document Types The `Documents` object array can include a variety of document types. As of now, the platform supports the following document types: | Document Type | Description | Supported file types | | ------------------------------ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `PASSPORT` | International travel document. | JPG, PNG | | `ID_DOCUMENT_FRONT` | Front side of a government-issued identity document. | JPG, PNG | | `ID_DOCUMENT_BACK` | Back side of the government-issued identity document. | JPG, PNG | | `DRIVER_LICENSE_FRONT` | Front side of a driver's license. | JPG, PNG | | `DRIVER_LICENSE_BACK` | Back side of a driver's license. | JPG, PNG | | `SELFIE` | A self-taken photograph for facial recognition verification. | JPG, PNG | | `PROOF_OF_ADDRESS` | Document verifying the user’s residential address. | JPG, PNG | | `PROOF_OF_FUNDS` | Documentation proving the user’s financial capabilities. | JPG, PNG | | `MC_DOCUMENT_FRONT` | Front side of a Matricula Consular (specific to certain countries). | JPG, PNG | | `MC_DOCUMENT_BACK` | Back side of a Matricula Consular (specific to certain countries). | JPG, PNG | | `ARTICLES_OF_INCORPORATION` | Registration document of a corporation. | JPG, PNG, PDF | | `CERTIFICATE_OF_GOOD_STANDING` | Confirms a company's legal registration and compliance with its jurisdiction's requirements. | JPG, PNG, PDF | | `UBO_FORM` | | Identifies a company's Ultimate Beneficial Owners and their ownership details | | `INE_FRONT` | Front side of a voter’s ID card (specific to certain countries). | JPG, PNG | | `INE_BACK` | Back side of the voter’s ID card (specific to certain countries). | JPG, PNG | ##### Integration in the Verification Process When these documents are submitted as part of a Dossier, they undergo verification processes tailored to their type. For instance, passport verification may involve different checks compared to driver's license verification. This specificity in the verification process not only enhances the accuracy of identity verification but also aligns with international standards and best practices. #### Document failed reasons The following table contains the reasons why a Document failed to be verified. | FAIL\_REASON | Description | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RETAKE_BARCODE_NOT_FOUND` | The document was classified as a type that contains a barcode but the barcode could not be found. | | `RETAKE_BARCODE_NOT_EXTRACTED` | The barcode was found but could not be read. | | `ERROR_BARCODE_FORMAT` | The barcode was read but the resulting data was not in the expected format. | | `ERROR_BARCODE` | A problem was encountered when trying to process barcode extraction and parsing. | | `RETAKE_FULL_DOCUMENT` | Data could not be extracted or the data was extracted, but did not pass our additional checks to ensure the extraction is accurate. | | `RETAKE_BACK_DOCUMENT` | Data could not be extracted from the back of the document. | | `RETAKE_FRONT_DOCUMENT` | The front of the ID document could not be extracted. | | `ERROR_DOCUMENT_NOT_SUPPORTED` | The document may or may not be classified but it is currently not supported for extraction. | | `RETAKE_IMAGE_FOCUS` | The image is out of focus. | | `RETAKE_IMAGE_GLARE` | Glare was found on the document preventing extraction or authentication. | | `RETAKE_IMAGE_BRIGHTNESS` | The image is too dark. | | `RETAKE_DOCUMENT_TOO_SMALL` | Retake Image - Try changing from portrait to landscape mode or getting closer to the image. | | `RETAKE_DOCUMENT_NOT_COMPLETE` | Retake Image - Ensure all four sides of the document are visible. | | `RETAKE_DOCUMENT_NOT_IDENTIFIED` | The type of document could not be identified. This could be caused by a low-quality image or it could be a document that is not supported. | | `ERROR_IMAGE_FORMAT_NOT_SUPPORTED` | Take a new image in a supported format. | | `RETAKE_IMAGE_TOO_SMALL` | Take a larger image. | | `RETAKE_IMAGE_TOO_LARGE` | Take a smaller image. | | `RETAKE_NO_IMAGE_FOUND` | The authenticator was not able to assess the document because the input image was missing. Ensure that at least one image of an identity document was captured and submitted in the service request. | | `RETAKE_DOCUMENT_IMAGE_QUALITY` | The authenticator was not able to assess the document because the image quality was too poor. Have the consumer capture a better quality image. | | `RETAKE_FIELDS_MISSING` | Field comparison could not be performed because there were not enough fields on the document to perform a data comparison. | | `ERROR_ESF_NOT_FOUND` | | | `ERROR_TAMPERED` | The Enhanced Security Feature (ESF) was found but shows evidence of tampering. | | `RETAKE_PORTRAIT_NOT_FOUND` | Unable to get a portrait image from an ID document. | | `RETAKE_SELFIE_NO_FACE` | Face Comparison requires two human faces; the face could not be detected in the selfie image. | | `RETAKE_PORTRAIT_NO_FACE` | Face Comparison requires two human faces; the face could not be detected in the cropped portrait image extracted from the document or in the document itself. | | `ERROR_DECODING_SELFIE` | Face Comparison could not be performed because there was a file decoding error with the selfie image. | | `ERROR_DECODING_DOCUMENT` | Face Comparison could not be performed because there was a file decoding error with the cropped portrait image or the ID document image. | | `RETAKE_PORTRAIT_NOT_FOUND` | The portrait on the document could not be located. | | `RETAKE_IMAGE_EXPOSURE` | Retake Image | | `ERROR_FONT_CONSISTENCY` | The fields used to determine font consistency did not return any extraction results | | `RETAKE_FACE_TOO_CLOSE` | Face Liveness could not be performed because the distance between the face and image border is too small. | | `RETAKE_FACE_NOT_DETECTED` | Face Liveness could not be performed because the face could not be detected in the image. | | `RETAKE_FACE_TOO_FAR` | Face Liveness could not be performed because the facial area is not big enough for analysis. | | `RETAKE_FACE_ANGLE` | Face Liveness could not be performed because the facial out-of-plane rotation angle is extremely large. | | `ERROR_DECODING_LIVENESS` | Face Liveness could not be performed because there was a file decoding error. | | `ERROR_ENCODING_LIVENESS` | Face Liveness could not be performed because there was a file encoding error. | | `RETAKE_MULTIPLE_FACES` | Face Liveness could not be performed because there is more than one face detected in the selfie image. | | `RETAKE_FACE_CROPPED` | Face Liveness could not be performed because the complete face is not present. | | `ERROR_AUTHENTICATION_TIMEOUT` | The authenticator took longer to process than was allowed to ensure a quick Mobile Verify Auto response. | | `ERROR_AUTHENTICATION_DOCUMENT` | This message is returned when an authenticity test was not applied to a document because the document doesn't have the necessary features or some design features prevent evaluation | | `ERROR_MRZ_NOT_FOUND` | The document was expected to have an MRZ (machine readable zone) on it based on its classification but no MRZ could be found. | | `ERROR_MRZ_FORMAT` | The MRZ (machine readable zone) was detected but was not in the proper format. | | `ERROR_MRZ_INVALID` | The MRZ (machine readable zone) check digits are invalid. | | `ERROR_SERVICE_UNAVAILABLE` | Service not currently available | | `RETAKE_DOCUMENT_TOO_CLOSE` | Document Liveness could not be performed because the document is too close to the camera. | | `RETAKE_DOCUMENT_BORDER_TOO_SMALL` | Document Liveness could not be performed because the distance between the document and image border is too small. | | `RETAKE_DOCUMENT_PARTIALLY_MISSING` | Document Liveness could not be performed because a part of the document is not visible in the image. | | `RETAKE_DOCUMENT_NOT_DETECTED` | Document Liveness could not be performed because the document could not be detected in the image. | | `RETAKE_DOCUMENT_TOO_SMALL` | Document Liveness could not be performed because the document size in the image is too small. | | `RETAKE_MULTIPLE_DOCUMENTS` | Document Liveness could not be performed because there are multiple documents in the image. | | `INVALID_FILE_FORMAT` | The file format (pdf, image) is not supported for this Document type. | ### Dossier Creation Creating a Dossier in our system begins by using the `Create Dossier` endpoint, where an Account's UUID is provided to link the Dossier to the respective account. During creation, the Dossier can be designated as "primary" through a boolean parameter. This indicates that it contains essential documents for the account's onboarding, centralizing the primary set of documents for identity verification. Dossiers can be created for Accounts in the following statuses: * `CREATED` * `PENDING_USER` * `ACTIVE` However, for Stakeholders, the parent Business account must also not have any of the following statuses: * `INACTIVE` * `DELETED` * `REJECTED` #### Supported Documents by Account type This section highlights the types of documents supported for verification within the platform. Each account type supports specific documents to comply with regulatory and compliance standards. Below, you will find tables detailing the document types associated with different account types. | Account Type | Document Types | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Business | `ARTICLES_OF_INCORPORATION`, `CERTIFICATE_OF_GOOD_STANDING`, `UBO_FORM`, `ORG_CHART` | | Consumer | `PASSPORT`, `ID_DOCUMENT_FRONT`, `ID_DOCUMENT_BACK`, `DRIVER_LICENSE_FRONT`, `DRIVER_LICENSE_BACK`, `SELFIE`, `PROOF_OF_ADDRESS`, `PROOF_OF_FUNDS`, `MC_DOCUMENT_FRONT`, `MC_DOCUMENT_BACK`, `INE_FRONT`, `INE_BACK` | | Stakeholder | `PASSPORT`, `ID_DOCUMENT_FRONT`, `ID_DOCUMENT_BACK`, `DRIVER_LICENSE_FRONT`, `DRIVER_LICENSE_BACK`, `SELFIE`, `PROOF_OF_ADDRESS`, `PROOF_OF_FUNDS`, `MC_DOCUMENT_FRONT`, `MC_DOCUMENT_BACK`, `INE_FRONT`, `INE_BACK` | ### Dossier updating/replacement When a document within a dossier fails the verification process, two approaches can be taken to address the issue: 1. **Updating a Document**: If only a specific document within the dossier needs to be corrected or modified, the failed document can be updated individually. This targeted approach allows for efficient handling of discrepancies or errors without impacting the rest of the dossier. 2. **Replacing the Entire Dossier**: If multiple documents within the dossier are incorrect or if a comprehensive update is required, the entire dossier, including all its documents, can be replaced with a new dossier. This approach ensures that all verification requirements are met while maintaining consistency across the submission. Dossiers can only be updated/replaced when **all** of the following conditions are met: 1. **Account Status**: The account must be in one of these statuses: 1. `CREATED` 2. `PENDING_USER` (specifically in the `DOCUMENTS` stage) 2. **Dossier Status**: The dossier must be in one of these statuses: 1. `EXPIRED` 2. `REJECTED` 3. `FAILED` 3. (_For Stakeholders only_) **Parent status**: The parent Business account must not have any of these statuses 1. `INACTIVE` 2. `DELETED` 3. `REJECTED` ### Documents Real-Time Verification ##### Feature Overview Real-time verification is a pivotal feature in our Dossier creation process, offering immediate feedback on the documents uploaded for onboarding. This functionality contrasts with the traditional method, where Dossiers are queued for verification after completing all KYC stages. ##### Advantages * **Immediate User Feedback**: One of the most significant advantages of real-time verification is the ability to provide instant feedback to users. As they upload their documents, any issues with the documents, such as poor image quality or incomplete information, can be immediately flagged. This immediacy allows users to rectify problems on the spot, enhancing the overall user experience and engagement. * **Improved Onboarding Process**: Instant feedback during the document upload process can significantly streamline user onboarding. It reduces the chances of delays in the verification process, thereby improving acquisition numbers and overall user satisfaction. ##### Implementation Considerations Real-time verification isn't universally applicable for all document types. To fully understand which documents are eligible for this feature, it is essential to consult with your Alviere program manager. They can provide detailed information about the types of documents that support real-time verification and guide you on how to best implement this feature for optimal results in your specific program. ##### Activation of Real-Time Verification To leverage the real-time verification feature in the Dossier creation process, it's essential to enable the `real_time_verification` boolean. This activation is a crucial step when creating a new Dossier and determines whether the submitted documents will undergo immediate verification. ##### Outcomes of Real-Time Verification * **Successful Verification**: If real-time verification is successful, the Dossier's status is updated to `VERIFIED`. This indicates that the documents have met all necessary criteria and are deemed acceptable for onboarding purposes. * **Verification Failure**: In instances where real-time verification does not succeed, the Dossier is marked with a status of `FAILED`. Crucially, the Dossier entity will include a `Documents` object array, encompassing a `fail_reasons` array of strings. This array provides detailed explanations for the failure of each submitted document. The inclusion of detailed reasons for verification failures is a key advantage of this feature. It not only aids users in understanding the specific issues with their documents but also streamlines the rectification process. Users can immediately address the highlighted problems, enhancing the chances of successful verification upon resubmission and significantly improving the overall efficiency of the onboarding process. ##### Example Scenario Consider a Dossier containing two documents: `ID_DOCUMENT_FRONT` and `ID_DOCUMENT_BACK`. If the real-time verification of the `ID_DOCUMENT_BACK` encounters issues, the corresponding `Document` in the Dossier will have a `fail_reasons` array containing a specific reason such as `RETAKE_BACK_DOCUMENT`. This granular feedback is instrumental in guiding users to take corrective actions, like retaking and resubmitting the backside of the ID document. # Activity Activity represents specific events related to an account that encompass a wider range of actions beyond card usage. These actions can include denied authorizations of card transactions, pin setting on cards, real-time verification of documents, payroll deposit switches, ACH pre notifications, ACH Notice of Changes (NOCs), and more. Monitoring these activities is crucial for security, compliance, and ensuring a seamless user experience across various financial operations. ### Activity Types Here we outline a broader spectrum of activity types, starting with denied authorizations and expanding to include other significant non-transactional activities: #### Denied Authorizations A denied authorization is an activity type that represents an attempt at a financial action (not limited to card transactions) that is not approved. Various reasons can lead to such denials, encompassing a wider range of financial operations beyond card transactions. Below is a comprehensive list of reasons for denied authorizations, applicable across various financial mechanisms: | Denied Reason | Reason Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ISSUER_ERROR` | Issuer error | | `CARD_CAPTURED_FRAUD` | Capture card due to suspected fraud | | `BLOCKED_MCC` | The MCC is blocked at a product or account level. Applies only to Mastercard | | `DEFAULT_DENY` | Default deny code when other deny codes do not apply. Also applicable to mobile-wallet provisioning red path or card not in active status for AVS-only checks | | `MAX_AMOUNT_LIMIT` | Maximum system amount reached. Applies only to Mastercard | | `INVALID_PAN` | Invalid PAN, not existing in the system. Applies to all card networks except Visa | | `FORMAT_ERROR` | Format error | | `REPORTED_LOST_FRAUD` | Card reported lost. Applies to all card networks except Visa | | `REPORTED_STOLEN_FRAUD` | Card reported stolen. Applies to all card networks except Visa | | `CLOSED_ACCOUNT` | Closed account or invalid account number. Applies only to Visa | | `INSUFFICIENT_FUNDS` | Insufficient funds or card in delinquent credit status | | `EXPIRY_DATE_ISSUE` | Card expiry issues | | `INVALID_PIN` | Invalid PIN entered | | `TRANSASCTION_NOT_PERMITTED` | Transaction not permitted to the cardholder | | `SUSPECTED_FRAUD` | Suspected fraud due to risk score. Applicable only to Visa and STAR | | `AMOUNT_LIMIT_EXCEEDED` | Violation of the per-transaction velocity limit. Applies to all card networks except Mastercard. | | `RESTRICTED_CARD` | Card used in an OFAC-restricted country (VISA) or frozen card (Mastercard and STAR) | | `SECURITY_VIOLATION` | Suspected fraud. Applicable only to Mastercard | | `MAX_TRANSACTION_VELOCITY` | Exceeds the maximum transaction count in a set period | | `MAX_PIN_COUNT` | Maximum failed PIN attempts exceeded | | `CARD_FROZEN_OR_CANCELED` | Frozen or canceled card | | `PARTIAL_APPROVAL` | The amount approved is less than the authorization request amount | | `AUTHORIZATION_DELAY` | Issuer didn't respond timely. Applicable only to Visa | | `SYSTEM_ERROR` | System error | | `INVALID_CVV2` | Mismatched CVV2 in card-not-present transaction. Applicable only to Visa | | `CHECKING_ACCOUNT_NOT_FOUND` | No checking account found for an ATM balance inquiry | | `SAVINGS_ACCOUNT_NOT_FOUND` | No savings account found for an ATM balance inquiry | | `INVALID_ACCOUNT` | Invalid FROM account for an ATM balance inquiry | #### Card Replacement/Reissuing Card Replacement/Reissuing is an activity type that signifies the issuance of a new card to an account holder, which can occur under two distinct scenarios: card replacement or card reissuing. These actions are integral to maintaining account security and ensuring continued access to financial services for the account holder. * **Replacement**: This occurs when a card is issued with a new Primary Account Number (PAN). A replacement is typically initiated in response to scenarios such as card loss, theft, or when there's suspected or confirmed fraud associated with the card. The issuance of a new PAN helps safeguard against unauthorized access and fraudulent transactions, essentially providing the account holder with a new account identity for their card-based transactions. * **Reissuing**: Unlike card replacement, reissuing involves issuing a new card with the same PAN as the previous card but with a different expiration date (and possibly a new CVV code). Reissuing is common in situations where the card is nearing its expiration date, has been damaged, or when the issuing institution transitions to cards with new security features or designs. The continuity of the PAN facilitates uninterrupted service, as it does not require updating payment information with merchants or service providers where the card is used for recurring payments. #### Payroll Deposit Switch This activity tracks when an account in our program utilizes our PDS solution to instruct their payroll provider to deposit funds directly into their digital wallet. # Check The Check entity is a key component within our financial platform, serving as a comprehensive hub for information on check deposits. It includes vital details like images of the check (both front and back), amount, currency, status, and payor information. Alviere's platform enhances the deposit process through its Remote Check Deposit Capture feature. This feature allows funds to be deposited into an Alviere wallet by capturing images of a cashier's check using our iOS or Android mobile applications. Integrated with Alviere's Mobile SDKs, this functionality ensures a smooth and efficient user experience. #### Transactions All activities within this module are classified as `CHECK_DEPOSIT` transactions. They follow the same rigorous workflow and regulatory standards as other ledger transactions on our platform. #### Processing a Check Our system employs advanced fraud detection techniques for check deposits. Users are required to add specific text on the back of the check as per the Alviere program guidelines. Both front and back images of the check must be captured and uploaded via Alviere's API for the deposit to be processed. Any discrepancies in the images can lead to the deposit being rejected. #### Service Fees Clients have the option to impose service fees for check deposits and for providing early access to funds. For instance, a fee of $10 could be applied for early fund release. ##### Fee Calculation When applying service fees for Check Deposits, only the `calc_type: "DEDUCT"` is permissible. This ensures service fees are subtracted from the clearing amount, preventing negative balances in customer accounts. These fees are then automatically transferred to the client's Service Fees account. #### Check statuses The following statuses are supported: | status | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CREATED` | This is the status of a Check once it has been submitted through the API indicating that the Check entity has been created. | | `PREVERIFIED` | This status pertains to a Check in which the image has been successfully uploaded to our platform and preverified for potential cybersecurity issues. | | `PROCESSING` | This status indicates that the Check has passed initial verification and is currently undergoing processing for approval and settlement. No further action is required at this stage. | | `CANCELED` | This stage represents a Check that has been canceled by our fraud teams due to account behavior prior to check processing. | | `ERROR` | This status indicates the rejection of a Check based on an automated system rule. The specific reason for the error can be obtained from the `status_reason` field. | | `REJECTED` | This status signifies the rejection of a Check by a compliance agent following the check processing stage. The specific reasons for the rejection can be obtained from the `rejected_reasons` field. | | `APPROVED` | This status signifies an approved Check that is currently pending settlement. | | `CLEARED` | This status represents a settled Check. | For Checks in `ERROR` status, the following `status_reason` are supported: | Reason | Description | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `ACCOUNT_NUMBER_NOT_READABLE` | The account number is not readable from the MICR. | | `AMOUNT` | There is an issue with the provided amount in the check. | | `AMOUNT_VARIANCE` | The difference between the entered and actual check amount exceeds a predetermined limit. | | `BACK_IMAGE` | Poor quality or missing data on the back image of the check. | | `BLACKLIST` | The entity is on a blacklist, usually for fraudulent activity. | | `BLANK_CHECK` | The check appears to be blank or incomplete. | | `BLOCKLIST` | The entity is on a blocklist, similar to a blacklist but often for different types of restrictions. | | `CODELINE_CHANGED_BY_DEPOSITOR` | Depositor might have tampered with the MICR. | | `DAILY_AMOUNT_LIMIT` | The total daily deposit amount has exceeded the user\`s limit. | | `DAILY_TRANSACTION_LIMIT` | The total number of daily transactions has exceeded the user\`s limit. | | `DUPLICATE` | The check appears to be a duplicate of another that has already been processed. | | `DUPLICATE_CHECK` | The check appears to be a duplicate of another that has already been processed based on information present in MICR. | | `DUPLICATE_PRIMARY_CODELINE_NO_CHECK_NUMBER` | The check appears to be a duplicate based on primary codeline not having a check number. | | `DUPLICATE_SECONDARY_CODELINE` | The check appears to be a duplicate based on secondary codeline. | | `DUPLICATE_SECONDARY_CODELINE_NO_CHECK_NUMBER` | The check appears to be a duplicate based on secondary codeline not having a check number. | | `FRONT_BACK_IMAGE` | Both front and back images of the check are either missing or of poor quality. | | `FRONT_IMAGE` | Poor quality or missing front image of the check. | | `GEOLOCATION` | Check deposit is attempted from a disallowed geographic location. | | `HIGH_SCORE` | A high-risk score based on various risk parameters, including possible fraudulent activity. | | `INSTITUTION_NAME_ERROR` | Mismatch or error in the name of the financial institution on the check. | | `INVALID_ACCOUNT` | The account number provided is incorrect or invalid. | | `INVALID_DATA` | Some data fields on the check are incorrect or not as expected. | | `INVALID_DOCUMENT` | The check document itself is invalid (e.g., torn, faded, etc., or not a check) | | `LOW_SCORE` | A low-risk score that still exceeds the acceptable risk parameters. | | `MEDIUM_SCORE` | A medium-risk score based on various risk parameters. | | `MICR_CODELINE_DOES_NOT_MATCH_OCR_CODELINE` | There's an issue matching the MICR codeline with the OCR codeline. | | `MICR_ERROR` | Error in the Magnetic Ink Character Recognition (MICR) code of the check. | | `MONTHLY_AMOUNT_LIMIT` | The total monthly deposit amount has exceeded the user\`s limit. | | `MONTHLY_TRANSACTION_LIMIT` | The total number of monthly transactions has exceeded the user\`s limit. | | `NEW_ACCOUNT` | The account into which the check is being deposited is newly opened and under initial observation. | | `NEW_USER` | The user is new and under initial observation, often with lower initial limits. | | `NO_ROUTING_TRANSIT_NUMBER_FOUND_IN_CODELINE` | The system is not able to detect a routing number in the MICR. | | `OCR_ERROR` | General Optical Character Recognition (OCR) error in reading the check. | | `OCR_ERROR_AMOUNT` | OCR error specifically related to the amount field on the check. | | `OCR_ERROR_CHECK_NUMBER` | OCR error specifically related to the check number. | | `OLD_CHECK` | The check is too old to be processed, exceeding the acceptable time limit. | | `OTHER` | Miscellaneous reasons not covered by the categories above. | | `PAYEE_ERROR` | Error or mismatch in the payee name on the check. | | `PAYER_PAYEE` | Conflict or error involving both the payer and payee names on the check. | | `POST_DATED` | The check is dated for a future date. | | `ROUTING_NUMBER_ERROR` | The routing number provided is incorrect or invalid. | | `ROUTING_NUMBER_NOT_AVAILABLE` | The routing number is missing from the check. | | `SIGNATURE_ERROR` | The signature on the check is missing, invalid, or doesn't match account records. | | `SYSTEM_ERROR` | An internal system error that prevents the check from being processed. | | `WATCHLIST` | The entity is on a watchlist for various reasons, which may include regulatory or compliance issues. | | `WEEKLY_AMOUNT_LIMIT` | The total weekly deposit amount has exceeded the user\`s limit. | | `WEEKLY_TRANSACTION_LIMIT` | The total number of weekly transactions has exceeded the user\`s limit. | For Checks in `REJECTED` status, the following `rejected_reasons` are supported: | Reason | Description | | -------------------------------------------------- | ------------------------------------------------------------------ | | `ALTERED_FICTITIOUS_ITEM` | Suspected fraudulent check. | | `CANNOT_DETERMINE_AMOUNT` | Unclear amount on the check. | | `CLOSED_ACCOUNT` | User's account is closed. | | `ENDORSEMENT_DOES_NOT_MEET_REQUIREMENTS` | Endorsement lacks required information or has fillers. | | `ENDORSEMENT_IRREGULAR` | Inadequate endorsement (missing or unclear signature/indications). | | `ENDORSEMENT_MISSING` | Missing signature and mobile deposit indication. | | `FROZEN_BLOCKED_ACCOUNT` | User's account is frozen or blocked. | | `MISSING_FOR_MOBILE_DEPOSIT_ONLY_WITH_ENDORSEMENT` | No mobile deposit indication on the endorsement. | | `NOT_SUFFICIENT_FUNDS` | Insufficient funds to cover the check. | | `NUMERIC_AND_WRITTEN_AMOUNTS_DIFFERENT` | Numeric and written amounts don't match. | | `POST_DATED` | Check is post-dated (future-dated). | | `SIGNATURES_IRREGULAR` | Unclear or missing signatures. | | `SIGNATURES_MISSING` | Missing signatures (front or back). | | `STALE_DATED` | Check's date exceeds 180 days. | | `STOP_PAYMENT` | General reason for check return. | | `UNABLE_TO_LOCATE_ACCOUNT` | Account not found for the given account number. | | `UNABLE_TO_PROCESS` | Check in poor condition, unrecognizable. | | `UNCOLLECTED_FUNDS_HOLD` | Uncollected funds from check deposit. | | `UNUSABLE_IMAGE` | Check image not clear. | # Overview Integrating with our platform is designed to be seamless and developer-friendly. Here's a brief overview to guide you through the process: ### **RESTful APIs** Our platform offers a comprehensive suite of RESTful APIs, ensuring predictable and resource-oriented interaction. These APIs have been meticulously designed to: * Utilize clear and logical URLs. * Accept form-encoded request bodies for simplicity. * Deliver JSON-encoded responses for easy parsing and integration. * Adhere to standard HTTP conventions, including response codes, authentication methods, and verbs. ### **Standard REST Methods** When working with our APIs, you can expect to interact using the following HTTP methods: * **POST**: To create and send a new resource to the system. * **PATCH**: For updating or modifying an existing resource. * **GET**: To retrieve data or query resources. * **DELETE**: To remove or cancel a particular resource. ### **Getting Started** To kick off your integration: 1. Gain access to the Portal. 2. Obtain your Authentication Credentials, which will be provided by your Alviere Program Manager. With these in place, you're all set to begin building your application and taking full advantage of the services offered by our platform. # Authentication Alviere uses the OpenID authentication standard. This section details what is required for authentication and access to the Alviere endpoints. #### Get API Credentials In order to connect to the API, you’ll need to have authentication credentials that should be provided by your Program Manager. If you don’t have authentication credentials yet, please request them by sending an email from your company email to . #### API Authentication In order to authenticate to the platform you'll need the following information: * `client_id`: Your unique client ID in the Alviere platform * `client_secret`: Your API key used to connect to the APIs; you may have more than one secret for your account #### Authentication Flow The following details the flow for authentication: 1. To call any of the APIs in the platform you'll need an access token, so this is always the service you need to call first. 2. The response object from the authentication endpoint will return multiple fields as per the JWT specification. Below are the most relevant: 1. `access_token`: The token that is used for all subsequent calls to the API 2. `expires_in`: The time limit after which the access token will expire; in seconds 3. On all subsequent calls to the API, you'll need to include a header in the HTTP request with that information.\ \ The format of the header is `Authorization: Bearer [your_access_token]` # Environments Integration with Alviere is facilitated through our Portal, combined with our comprehensive APIs and SDKs. We understand the importance of a robust testing environment as well as a reliable production environment. To cater to this, we offer two distinct environments: | **Environment** | **Portal URL** | **API URL** | | --------------- | -------------------------------- | ----------------------------- | | Sandbox | | | | Production | | | ## Sandbox * The Sandbox environment is tailored for development and testing purposes. * Provides an isolated testing platform to integrate and test functionalities using the Sandbox API. * Note that the Sandbox environment does not interface with backend systems, so functionalities like KYC/KYB validations or real-money transfers between wallets or bank accounts are not supported. ## Production * This environment is integrated with the full suite of Alviere platform capabilities and our partners. * Access to functionalities within this environment is contingent upon the configuration settings specific to your program. # Metadata The Alviere Platform supports updateable Metadata on select objects allowing you to add information to the request. This is available using the `metadata` parameter. Metadata can be useful for storing additional, structured information on an entity. For example - you could store your user's internal account number and corresponding unique identifier from your system on a Alviere Account entity. _Note_: Any Metadata provided in the request is not used by Alviere. The field is reserved for your use to make your overall integration architecture more efficient. Metadata takes the form of free-form key-value pairs. You may send Metadata for select methods when you create an object (POST) and when updating an object (PATCH). We do not recommend submitting any sensitive information (i.e. bank account numbers, card details, complete social security numbers, etc.) as Metadata. Example with added Metadata: - **PATCH {url}/accounts/{account_uuid}** ```json { "information": { "consumer_information": { "first_name": "John", "middle_name": "Smith", "last_name": "Doe", "date_of_birth": "1976-02-07", "ssn": "123456789", "phone_number": "+19171326500", "email_address": "john.doe@alviere.com" } }, "metadata": { "customer_id": "35082920" }, "external_id": "string" } ``` If you would like to remove metadata that is already on an object, you can send a PATCH with an empty key `{}`. Example removing metadata: - **PATCH {url}/accounts/{account_uuid}** ```json { "information": { "consumer_information": { "first_name": "John", "middle_name": "Smith", "last_name": "Doe", "date_of_birth": "1976-02-07", "ssn": "123456789", "phone_number": "+19172316500", "email_address": "john.doe@alviere.com" } }, "metadata": {}, "external_id": "string" } ``` **Example use cases for Metadata**: - Link IDs - attach your system's unique ID to an available Alviere entity allowing for easy lookups. For example - add a customer ID to an Alviere Account or add a location to Load or Withdrawal Funds, your promo code to Create Card, etc. - Customer specifics - add notes about a customer by storing your internal ID and comments. # Error Codes Alviere employs standardized HTTP response codes to convey the outcome of API requests. Each response code provides insights into whether a request was successful, requires redirection, has client-induced errors, or encountered server-side issues. ### **Categories of HTTP Response Codes:** * **2xx (Success)**: The request was processed successfully and contains no errors. * **3xx (Redirection)**: Additional actions are needed to finalize the request. * **4xx (Client Error)**: The request contains inaccuracies, often stemming from the client side. * **5xx (Server Error)**: These indicate issues within our infrastructure and are uncommon. * **Urgent Action Required**: Should you encounter any 5xx errors, please reach out to us without delay at . ### **Common HTTP error codes** | Code | Text | Description | | ------- | -------------- | ------------------------------------------------------------------------------------ | | 201 | OK | The request was executed successfully. | | 400 | Bad Request | The request was inappropriate, likely due to missing parameters. | | 401 | Not authorized | The request wasn't authorized or had an invalid or missing API Token. | | 403 | Forbidden | The provided API Token lacks the required permissions. | | 404 | Not Found | The sought-after resource isn't available. | | 409 | Conflict | The request is in conflict with another, possibly due to identical idempotency keys. | | 500-504 | Server Error | There was an unexpected issue on our side. | ### **API error codes** In addition to the status code, some response bodies will also contain a `Validation` section, indicating the specific outcome of your request. This encompasses: * **Result**: Specifies if the request was "Accepted" or "Denied". * **Error code**: A unique identifier linked to a recognisable request error. * **Description**: Elaborates on the particular error encountered. If the request has no issues, these fields remain unpopulated. #### Sample response ```json { "validation": { "result": "REJECTED", "error_code": "500012", "error_description": "Payment method is invalid" } } ``` #### List of error codes (HTTP 400 responses) | Error Code | Description | | ---------- | -------------------------------------------------------------------------------------- | | 100011 | The system couldn't process the encrypted data | | 100012 | The encrypted data's endpoint is incorrect or corrupted | | 100013 | The system can't decode the encrypted data at the endpoint | | 100014 | The decrypted data at the endpoint is incorrect or unusable | | 100015 | The endpoint for the decrypted data is wrong | | 100016 | The specified version or destination endpoint is incorrect | | 100017 | The ongoing operation was stopped | | 100018 | Either client\_id and client\_secret or authorization token should be provided | | 100019 | client\_id and client\_secret can't coexist with authorization token | | 100020 | authorization token provided without an account uuid | | 100021 | Could not generate authorization token | | 100022 | Could not parse authorization token | | 100023 | Could not parse jwt account uuid | | 100024 | Could not retrieve account | | 100025 | Invalid jwt | | 100026 | Could not generate auth response | | 100027 | Could not get public certificate | | 100028 | Invalid account ownership | | 100029 | Account is deleted | | 100030 | Account is not consumer or business | | 100300 | Invalid request payload | | 100301 | Invalid request payload field | | 100302 | Invalid path parameter | | 100303 | Invalid header | | 100304 | Invalid query parameter | | 100305 | Invalid Authorization token | | 100306 | Authorization failed | | 110000 | Session not found | | 110001 | Parent account not found | | 110002 | Not found | | 110004 | Account type is not eligible to use this api | | 1016008 | Action not allowed because of current account status | | 200100 | Duplicate external id | | 200101 | Duplicate external id | | 200300 | Invalid payload | | 200301 | Invalid request | | 200302 | Invalid path parameter | | 200303 | Invalid header | | 210001 | Implementation error : invalid account ownership | | 210002 | Transaction not found | | 216001 | Transaction cannot be refunded | | 216002 | Transaction is already refunded | | 216005 | Partial refund not supported | | 216006 | Multiple partial refunds not supported | | 230002 | Implementation error : invalid account ownership | | 230003 | Payment method is not related to plaid | | 232001 | Account status is not ACTIVE | | 232005 | Action is not permitted because account type is not consumer | | 232007 | Action is not permitted because account type is not Business | | 232008 | Account type is not Business | | 232009 | Configuration error: payment instruments | | 232010 | Configuration error: payment methods | | 232011 | Configuration error: 3DS Failure url | | 232012 | Configuration error: 3DS Success url | | 232013 | Transaction cannot be authorized because wallet type is not checking | | 232014 | Integration error: account type is not allowed to perform the action | | 233001 | Card payment method is not active | | 233003 | Payment instrument is not active | | 233004 | Payment instrument not found | | 233006 | Payment instrument invalid | | 233007 | Portal error | | 234004 | Bank not found | | 310001 | Invalid payload | | 310002 | Invalid request | | 310003 | Invalid headers | | 310004 | Invalid get parameters | | 310005 | Invalid path parameters | | 310008 | Invalid currency | | 320001 | Account not found | | 320002 | Implementation error : invalid account ownership | | 320004 | Account already exists | | 320005 | Action not permitted because Account is not of type CONSUMER | | 320006 | Action not permitted because Account is not of type PROGRAM | | 320009 | Account already deleted | | 320010 | Action not permitted because Account status is PROCESSING | | 320011 | Account already inactivated | | 320013 | Account already activated | | 320016 | Action not permitted because Account status is not ACTIVE | | 320017 | Action not permitted because Account status is not ACTIVE or CREATED | | 320018 | Action not permitted because Account status is not ACTIVE , CREATED or PENDING\_USER | | 320019 | Action not permitted because Account status is REJECTED or DELETED | | 320020 | Action not permitted because Account status is not INACTIVE | | 320028 | Action not permitted because of Invalid Account type | | 320031 | Duplicate external ID for Account | | 320041 | Invalid request : Account type not supported | | 320053 | Action not permitted because Account status is REJECTED or DELETED | | 320059 | Dossier Cannot be created because Account status is not CREATED or PENDING\_USER | | 320062 | Account is not of Wallet or Consumer type | | 320063 | Wallet not found | | 320070 | Action not allowed because account status is not CREATED or PENDING\_USER | | 320081 | Invalid account type | | 320082 | Action cannot be performed on Consumer account type | | 320090 | Account is not of type BUSINESS | | 320091 | Account is not of type STAKEHOLDER | | 320092 | ID Documents from a country that is not supported | | 320093 | ID document type is not supported | | 320094 | Action cannot be performed on this account type | | 320095 | ID information is missing | | 320096 | Account type is not CONSUMER or STAKEHOLDER | | 320097 | Account type is not CONSUMER or BUSINESS | | 320098 | Account is not of type CARDHOLDER | | 320108 | Action not permitted because account status is MANUAL\_REVIEW | | 320115 | Account age is below required minimum or above maximum | | 320116 | Action not permitted because this account type is not allowed | | 320117 | Action not permitted because Account type is not allowed to create dossier | | 320118 | Profile is Invalid | | 320120 | Configuration error: profile related error | | 320122 | Wallet is not active yet | | 320123 | Action not allowed for this account type | | 320126 | Action not allowed because of current account status | | 320127 | Action not allowed due to account status | | 329500 | Account is not of type BENEFICIARY | | 329501 | Beneficiary doesn't belong to expected parent | | 329503 | Beneficiary not found | | 329505 | Beneficiary must have bank | | 329506 | Beneficiary currency not allowed | | 329520 | Beneficiary country error | | 329523 | Beneficiary first name error | | 329524 | Beneficiary last name error | | 329537 | Beneficiary details missing error | | 329546 | Beneficiary clabe missing/Invalid error | | 329551 | Beneficiary status does not allow fields to be updated | | 329552 | Local Beneficiary country not allowed | | 329553 | Local Beneficiary currency not allowed | | 329554 | Local Beneficiary Ach Account not valid | | 329555 | Local Beneficiary not valid bank type | | 329557 | International Beneficiary Clabe Account not valid | | 329559 | Local Beneficiary missing ach bank Account details | | 329565 | Beneficiary legal type not allowed | | 329567 | Beneficiary legal type does not allow these update values | | 329568 | International Beneficiary cash pickup location not valid | | 329569 | Beneficiary bank code or cash pickup location missing/Invalid error | | 329570 | Beneficiary cash pickup location missing/Invalid error | | 329575 | Beneficiary payout method country error | | 329576 | Beneficiary payout method currency error | | 329577 | Invalid request : international beneficiary cant have bank type | | 329579 | Action not allowed because beneficiary has transactions being processed | | 329580 | International Beneficiary country not allowed | | 329581 | International Beneficiary country not allowed | | 329582 | Beneficiary phone number missing/invalid | | 329583 | Beneficiary address missing/invalid | | 329584 | Beneficiary IBAN missing/invalid | | 329585 | Beneficiary SWIFT missing/invalid | | 329586 | Beneficiary SWIFT bank missing | | 329587 | Beneficiary SWIFT bank not found | | 329588 | Beneficiary SWIFT bank country does not match | | 329589 | Beneficiary Tax ID missing/invalid | | 329590 | Beneficiary EFT bank missing/invalid | | 329591 | Beneficiary country change not allowed | | 329602 | Business is not an allowed Account type | | 329615 | Business country of incorporation not allowed | | 329616 | Business Account doesn't belong to program | | 329618 | One of the stakeholders already exists | | 329619 | Business account status does not allow fields to be updated | | 329620 | Business country of incorporation is different | | 329622 | Invalid request | | 329624 | Action not allowed | | 329701 | The parent Business Account is in an Invalid status | | 329704 | Stakeholder Business Account not found | | 329705 | Invalid data for stakeholder type | | 329707 | the total percentage is larger than 100 | | 329803 | Cardholder is not an allowed Account type | | 329804 | Cardholder account's parent type is not CONSUMER | | 329806 | Cardholder account update request not allowed | | 329809 | Cardholder account's parent is not active | | 329812 | Cardholder account not found | | 329910 | Configuration error : bank missing | | 329912 | Configuration error : documents combo missing | | 329913 | Configuration error : maximum wallet missing | | 329914 | Configuration error : maximum currency per wallet missing | | 329915 | Configuration error : maximum wallet for specified type not found | | 329930 | Invalid request | | 329934 | Configuration error : bank missing | | 329935 | Configuration error : bank missing | | 329939 | Country of issuance not allowed | | 330000 | Profile not found | | 330005 | Profile changes are not allowed | | 335000 | Card payment method belongs to a different account | | 335001 | Card payment method not found | | 335002 | Duplicate external id | | 335028 | Card already deleted | | 335029 | Card allowed payment method limit exceeded | | 335030 | Name on card must be set | | 335035 | Invalid Request: 3ds preference | | 340000 | Bank not found | | 340001 | Bank payment method doesnt belong to this particular account | | 340004 | Duplicate external id | | 340012 | Bank payment method update not allowed | | 340016 | Bank payment method update not allowed | | 340018 | Bank payment method already deleted | | 340019 | Bank payment method allowed limit exceeded | | 340021 | Configuration error : bank account type not supported | | 340022 | Invalid request : bank account format not supported | | 340027 | Duplicate customer external id | | 340028 | Bank not active | | 341000 | Action not permitted because payment method not associated with plaid | | 341001 | Action not permitted because payment method is associated with plaid | | 342000 | Number of maximum Wallets for Account already reached | | 343002 | Payout method already exists | | 343003 | Payout method type is Invalid | | 343005 | Payout method not found | | 343006 | Payout method not found | | 343009 | Duplicate external id | | 350000 | Duplicate primary address | | 350001 | Primary address must be created first | | 350004 | Primary address cannot be deleted | | 350005 | Address already deleted | | 350016 | Duplicate external id | | 350018 | Invalid request: missing state | | 350019 | Invalid request : state malformed | | 350020 | Invalid request : address country not allowed | | 350021 | Needs full billing address as account doesn't have a primary address | | 385031 | Invalid request : 3ds not supported | | 390202 | Dossier already exists | | 390203 | Dossier status is not allowed to perform action, must be Expired or Rejected or Failed | | 390204 | Dossier already deleted | | 390206 | Dossier not found | | 390207 | Dossier not found | | 390210 | Duplicate primary dossier | | 390211 | Primary dossier must be created first | | 390213 | Action not permitted because dossier status must be Created | | 390214 | Action not permitted because dossier status must be Expired or Failed | | 390215 | Replace not permitted because of current dossier status | | 390217 | Action not allowed for this account type | | 390218 | Action not allowed because of current account status | | 390219 | Configuration error : program not allowed to use real time verification feature | | 390220 | Real time validation retry threshold reached | | 390221 | Documents issuance country not eligible for realtime verification | | 390305 | Document type could not be matched | | 390311 | Implementation Error: Ownership mismatch | | 390703 | Payment instrument not found | | 390704 | Payment instrument doesnt belong to this account | | 390706 | Payment instrument already deleted | | 390805 | Action not allowed because of profile request status | | 391001 | Funding instrument already exists | | 391003 | Funding instrument not found | | 391100 | Barcode code usage limit exceeded | | 410000 | Account not found | | 410002 | Configuration error : service fees vault is missing | | 410200 | Transaction not permitted because the Account type is not vault | | 410201 | Transaction not permitted because Account type is not program | | 410202 | Transaction not permitted because the Account type is not vault | | 410203 | Transaction not permitted because the Account type is not Business | | 411000 | Transaction not permitted because account not found | | 411001 | Vault does not support withdrawal | | 411002 | Vault does not support deposit | | 411003 | Configuration error : Vault property | | 411004 | Transaction not permitted because Account is not active | | 411005 | Transaction not permitted because of ownership mismatch | | 411007 | Transaction not permitted because of current Account status | | 411008 | Account has similar transaction in manual review | | 411009 | Transaction not permitted because account not FBO | | 412000 | Configuration error: prefunding is not allowed | | 412100 | Transaction not permitted because of max balance limit | | 412101 | Transaction not permitted because of max balance limit | | 412102 | Origin and Destination vault groups differ from each other | | 415000 | Wallet not found | | 415002 | Wallet type Invalid | | 415003 | Wallet status Invalid | | 415004 | Wallet not found | | 415005 | Transaction not permitted because Wallet is not active | | 415006 | Origin Wallet and Destination Wallet Currency are not the same | | 420001 | Transaction not permitted because of insufficient funds | | 420002 | Funds above maximum allowed | | 420006 | Not sufficient funds | | 420007 | Account balance is negative | | 420014 | Transaction not permitted because the Wallet balance is negative | | 430000 | Transaction does not exist | | 430001 | Idempotency error: transaction already exists in the system | | 430006 | Transaction already refunded | | 430100 | Invalid request: amount | | 430102 | Same origin and destination Wallet | | 430103 | Configuration error: minimum transaction amount | | 430104 | Configuration error: maximum transaction amount | | 430105 | Transaction action not allowed | | 430106 | Transaction not permitted because amount exceeds daily limit | | 430107 | Transaction not permitted because amount exceeds Account allowed rolling period limit | | 430108 | Transaction not permitted because amount below Account allowed minimum | | 430109 | Transaction not permitted because amount exceeds Account allowed maximum | | 430110 | Transaction not permitted because amount exceeds Account allowed daily limit | | 430111 | Transaction not permitted because amount exceeds Account allowed rolling period limit | | 430201 | Transaction action cannot be performed because of current transaction status | | 430204 | Action not permitted | | 430400 | Transaction not permitted | | 430409 | Action not allowed due to missing refund method | | 430410 | Action not allowed due to missing refund method | | 430411 | Action not allowed due to missing or invalid status reason | | 430412 | Transaction not allowed because of address state | | 430413 | Invalid refund method | | 430502 | Receipt not found | | 430602 | Transaction is not cancelable | | 430700 | Transactions statement period Invalid | | 430701 | Transactions statement period not available | | 432000 | Invalid service fee type | | 432001 | Invalid service fee description | | 432002 | Invalid fee type | | 432003 | Bad Request: Amount is NULL or Negative for Fee Type = AMOUNT | | 432004 | Bad Request: Percent is NULL or not between 0 and 100 | | 432005 | Bad Request: Cap is NULL or Negative for a PERCENT\_CAPPED type | | 432006 | Invalid request | | 432100 | Invalid request | | 433000 | Remittance quote not found | | 433001 | Remittance quote already processed | | 433003 | Remittance quote not found | | 433004 | Remittance quote is expired | | 450000 | Invalid request: payment method not found | | 450002 | Payment method Invalid | | 450003 | Payment method is not active | | 450004 | Payment method not found | | 452000 | Beneficiary not found | | 452001 | Beneficiary is not active | | 452002 | Invalid account ownership | | 460000 | Currency not found | | 460100 | Currency not allowed | | 492001 | Invalid Request : exchange\_rate cannot be passed | | 492002 | Invalid Request : exchange\_rate is required | | 492004 | Implementation error: ownership mismatch | | 492005 | Beneficiary is not active | | 492008 | Beneficiary is not international | | 492009 | Transaction not found | | 492010 | Invalid quote | | 492011 | Payout method does not belong to Beneficiary | | 492018 | Invalid transaction purpose | | 492019 | Invalid source of funds | | 492020 | Invalid phone number | | 492021 | Business Account is missing incorporation date | | 494001 | Account not found | | 494003 | Beneficiary not local | | 494005 | Payout method not found | | 494007 | Implementation error: ownership mismatch | | 494008 | Invalid funding method | | 499001 | Invalid request error | | 499003 | Invalid request : missing parameter | | 500003 | Invalid Headers | | 510000 | Action not allowed because Issued card was not found | | 510002 | Issued card doesnt not found | | 510003 | Issued card action not possible to be performed | | 510004 | Issued card not active | | 510007 | Issued card is not ready to activate | | 510015 | Issued card already active | | 510016 | Issued card is not physical | | 510017 | Issued card is blocked | | 510018 | Account status is not in a valid state for card activation | | 510019 | Card info missing for activation | | 510021 | Shipping address is not valid | | 510023 | Issued card already created | | 510028 | Card brand is not supported | | 510029 | Card not found | | 510030 | Mastercard parameters not present for a Mastercard card | | 510031 | VISA parameters not present for a VISA card | | 510032 | Action not allowed because associated card doesn't have any address | | 510033 | Configuration error : incentives are not allowed for the program | | 510034 | Configuration error : product id is not set | | 510036 | Invalid request : initial balance must be sent for this issued card type | | 510037 | Invalid request : initial balance should not be sent | | 510038 | Configuration error: merchants are not allowed | | 510039 | Configuration error: custom field emboss id is missing for the card product | | 510040 | Invalid request : emboss id is missing | | 510041 | Configuration error : custom field shipping method not allowed | | 510042 | Name on card issued too long | | 510043 | Invalid request : name on card is Invalid | | 510044 | Maximum issued card limit reached | | 510045 | Invalid request: duplicate external id | | 510046 | Configuration error : incentives are not allowed for the program | | 510047 | Card not found | | 510048 | Card type is not allowed for wallet type | | 510049 | Maximum issued card limit reached | | 510060 | Configuration error : carrier\_id is missing | | 510061 | Carrier\_id is missing | | 510062 | Carrier\_id cannot be passed | | 510064 | Card is not ACTIVE | | 510066 | Provided card pin is not valid | | 510067 | Card is BLOCKED | | 510068 | Card product is missing from Configuration | | 510072 | Configuration error: card issued type | | 510073 | Configuration error: pin length missing | | 510075 | Invalid service fee | | 510076 | Duplicate service fee external id | | 510078 | Action not possible because of card status | | 510079 | Card initial balance doesn't cover deduct service fees | | 510080 | Invalid card genre for usage of carrier message | | 510082 | Configuration error: name length | | 510083 | Action not allowed for this card type | | 510084 | Card replace not allowed due to insufficient funds | | 510085 | Card replace not allowed for card genre | | 510086 | Card replace not possible to be performed | | 510088 | Card replace not allowed for card status | | 510091 | Card has already been replaced | | 510092 | Invalid card type for usage of carrier message | | 510094 | The requested card operation is not yet supported | | 510095 | Emboss\_id is Invalid | | 510096 | Configuration error : generic card issuance | | 510103 | Card replace duplicate | | 510104 | Card genre Invalid | | 510105 | Invalid Wallet type | | 510107 | line\_2 text not allowed in the request | | 510108 | carrier\_id not allowed in the request | | 510118 | Card is frozen | | 510119 | Cannot add card to digital wallet | | 515001 | Invalid get parameters | | 515002 | Invalid path parameters | | 515004 | Invalid request | | 515005 | Invalid payload | | 515006 | Invalid Expiration Date | | 515007 | Invalid Expiration Times | | 515008 | Wallet uuid Invalid | | 515009 | Card uuid Invalid | | 515010 | Program uuid required | | 520001 | Implementation error : invalid account ownership | | 520003 | Account status is not allowed, must be Active | | 520004 | Account status is Invalid | | 520012 | Wallet must be active | | 520014 | Action not possible because consumer account not available | | 520015 | Configuration error: maximum cards | | 520020 | Wallet not found | | 520021 | Action not supported for this account type | | 520022 | Action not supported for this account type | | 520023 | Account has insufficient balance | | 520025 | Account has negative funds | | 520035 | Not found | | 520036 | Action not allowed because of current account status | | 530000 | No incentive rule found | | 530001 | Incentive rule not found | | 530003 | Incentive rule already deleted | | 530009 | Incentive rule already exist | | 530010 | Incentive rule already activated | | 530011 | Incentive rule already inactivated | | 531004 | Card incentive already exists | | 531005 | Card incentive duplicate in request | | 532004 | Service fee already exist | | 610000 | Account not found | | 610002 | Implementation error : invalid account ownership | | 610004 | Account is already deleted | | 610007 | Account not type consumer | | 610013 | Account is rejected | | 610014 | Account already verified | | 610016 | at least one active stakeholder should exist | | 625027 | account not ready for validation yet | | 627000 | Transaction not found | | 699101 | System error (e.g., a temporary problem with Alviere's servers) | | 699400 | Portal error | | 710001 | Invalid Payload | | 710002 | Invalid Request | | 710003 | Invalid Headers | | 710005 | Invalid Path Parameters | | 715000 | Account or Wallet Not Found | | 715001 | Only Account Type Consumer Is Permitted to Do This Transaction | | 715002 | Account Is Not Active | | 715003 | Implementation Error: Invalid Account Ownership | | 715004 | Wallet Is Not Active | | 715006 | Invalid Wallet Type | | 715007 | Action not allowed because of current account status | | 715008 | Action not allowed because of current account status | | 720003 | Check Already Exists | | 720004 | No Relevant | | 720005 | Check Not Found | | 720014 | Check Not Found | | 720018 | Check Deposit Transaction Denied, Max Balance Exceeded | | 720019 | Check Deposit Transaction Denied, Amount Below Account Allowed Minimum | | 720020 | Check Deposit Transaction Denied, Amount Above Account Allowed Maximum | | 720021 | Check Deposit Transaction Denied, Amount Exceeds Account Allowed Daily Limit | | 720022 | Check Deposit Transaction Denied, Amount Exceeds Account Allowed Rolling Period Limit | | 720023 | Check Return Not Found | | 720026 | Transaction Type Not Allowed for This Wallet | | 720028 | Invalid Request: Service Fee Amount Is Wrong | | 910001 | Invalid Payload | | 910002 | Invalid Request | | 910003 | Invalid Headers | | 910004 | Invalid Get Parameters | | 910005 | Invalid Path Parameters | | 915001 | Consumer Account Status Is Not Active | | 915002 | Consumer Account Status Is Not Active | | 915003 | Wallet Type Is Not Checking | | 915004 | DDA Not Found | | 915005 | Implementation Error: Invalid Account Ownership | | 915006 | Action Not Permitted Because Account Type Is Not Consumer | # Mock Services The Alviere Sandbox Environment operates independently of external third-party services typically involved in executing transactions. To bridge this gap, we have integrated mock services and scenarios that replicate the production environment experience. These simulated examples are designed to facilitate your testing process, helping you to prepare for various situations that may arise when customers start using your services. Please be aware that not all of these scenarios may be necessary or compatible with your particular program. It's important to consult with your Alviere implementation team to identify which scenarios are relevant to your needs. For instance, in the case of KYC, if your program is limited to the IDENTITY and SANCTIONS Processing Stages, only those specific test conditions can be utilized. Attempting to use test conditions from other Processing Stages will lead to the Account status changing to ACTIVE, provided all required data attributes are submitted, as these conditions might not be pertinent to your program's setup. ## KYC During the Account onboarding process, we created scenarios to simulate different Processing Stages of the identity validation process. This is accomplished by submitting specific data attributes during the `Create Account` requests. The table below outlines the conditions that should be used to trigger the different account statuses. Note that data attributes submitted in the request outside of the conditions below will result in all processing stages being automatically accepted where the Account status results in being `ACTIVE`. | Processing Stage | Test Conditions | Account Status and (Status Reason) | Action required to advance the entity to the next stage | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FRAUD | _email\_address_ contains: `deny_` For example:- `{name}+deny_1@anydomain.com` - `{name}+deny_123@anydomain.com` | REJECTED | N/A | | FRAUD | _email\_address_ contains: `manual_` For example:- `{name}+manual_1@anydomain.com` - `{name}+manual_123@anydomain.com` | MANUAL\_REVIEW | Accept / Reject the Account in MANUAL\_REVIEW | | ADDRESS | Following `postal_code` and `state` combinations:- `postal_code` starts with `82007` - `state` equals `WY`or- `postal_code` starts with `28748` - state equals `NC` | PENDING\_USER (INVALID\_ADDRESS) | Update the Address with another `postal_code` and `state` combination | | ADDRESS | Address `line_1` or `line_2` match regex (PO box variants): `^(((p[\s.]?[o\s][.]?)\s?)\|(post\s?office\s?))((box\|bin\|b.?)?\s?(num\|number\|#)?\s?\d+)` For example:- `PO Box 123` - `P.O. Box 123` | PENDING\_USER (INVALID\_ADDRESS) | Update the Address with another other `line_1` or `line_2` address | | IDENTITY / IDENTITY\_OPTIONAL\_SSN | Requires all variables in the combinations below- `first_name` equals `Ben` - `last_name` equals `Wyatt` - `ssn` ends in `3333` - `date_of_birth` equals `1974-01-01` | PENDING\_USER (INVALID\_NAME) | Update the Account with any other combination of consumer information | | IDENTITY / IDENTITY\_OPTIONAL\_SSN | Requires all variables in the combinations below- `first_name` equals `Un` - `last_name` equals `Born` - `date_of_birth` YEAR equals `1900`or `1974` - Any `ssn` should be provided | PENDING\_USER (INVALID\_DOB) | Update the Account with any other combination of consumer information | | IDENTITY / IDENTITY\_OPTIONAL\_SSN | Requires all variables in the combinations below:- `first_name` equals `Leslie` - `middle_name` equals `Barbara` - `last_name` equals `Knope` - `ssn` ends in `6788` - `date_of_birth` equals `1975-01-18` - `phone_number` equals `+11236547890`or- `first_name` equals `Ella` - `last_name` equals `Phone` - `ssn` ends in `666` | PENDING\_USER (INVALID\_PHONE) | Update the Account with any other combination of consumer information | | IDENTITY / IDENTITY\_OPTIONAL\_SSN | Requires all variables in the combinations below- `first_name` equals `Jeremy` - `last_name` equals `Clarkson` - or - `ssn` ends in one of `9009`, `9010` or `1906` | PENDING\_USER (INVALID\_SSN) | Update the Account with any other combination of consumer information | | IDENTITY\_OPTIONAL\_SSN | To test a Consumer that provides a Mexican ID or Passport, no SSN provided, and the system does NOT find a SSN match. Requires all variables in the combinations below:- `first_name` equals `James` - `last_name` equals `Smith` - All other information (i.e. address, phone, etc…) should be provided including the documents (i.e. MC\_DOCUMENT\_FRONT, MC\_DOCUMENT\_BACK, SELFIE) | ACTIVE | N/A | | IDENTITY\_OPTIONAL\_SSN | To test a Consumer that provides a Mexican ID or Passport, no SSN provided, and the system finds a SSN match. Requires all variables in the combinations below:- `first_name` equals `James` - `last_name` equals `May` - All other information (i.e. address, phone, etc…) should be provided including the documents (i.e. MC\_DOCUMENT\_FRONT, MC\_DOCUMENT\_BACK, SELFIE) | PENDING\_USER (REQURES\_LAST\_4\_SSN) | Update the Account with any `ssn` value (4 or 9 digits) | | DOCUMENTS / DOCUMENTS\_OPTIONAL\_FULL\_SSN | `last_name` equals `Undocumented` | PENDING\_USER (INVALID\_DOSSIER) | Update the Dossier with a generic drivers license front and back as provided below | | DOCUMENTS / DOCUMENTS\_OPTIONAL\_FULL\_SSN | `last_name` equals `invalidDOB` | PENDING\_USER (INVALID\_DOB) | Update the Account with `date_of_birth` equals `1980-01-29` | | DOCUMENTS / DOCUMENTS\_OPTIONAL\_FULL\_SSN | `last_name` equals `invalidName` | PENDING\_USER (INVALID\_NAME) | Update the Account with a different last name | | DOCUMENTS / DOCUMENTS\_OPTIONAL\_FULL\_SSN | `last_name` equals `ExpiredDoc` | PENDING\_USER (EXPIRED\_DOCUMENT) | Update the Account with a different last name | | DOCUMENTS / DOCUMENTS\_OPTIONAL\_FULL\_SSN | `last_name` equals `Verifications` | MANUAL\_REVIEW (INVALID\_DOSSIER) | Accept / Reject the Account in MANUAL\_REVIEW | | DOCUMENTS\_OPTIONAL\_FULL\_SSN | `ssn` only contains last 4 | PENDING\_USER (REQUIRES\_DOSSIER) | Submit a dossier/documents | | DOCUMENTS\_OPTIONAL\_FULL\_SSN | `last_name` equals `InvalidClassificationCountry` or `InvalidCountry` | PENDING\_USER (COUNTRY\_OF\_ISSUANCE\_MISMATCH) | Update the Account with a different last name | | DOCUMENTS\_OPTIONAL\_FULL\_SSN | `last_name` equals `CountryNotSupported` | PENDING\_USER (COUNTRY\_OF\_ISSUANCE\_NOT\_SUPPORTED) | Update the Account with a different last name | | SANCTIONS | `last_name` equals `Badguy` | MANUAL\_REVIEW | Accept / Reject the Account in MANUAL\_REVIEW | ## Card Issuance When a card is created it will flow through various statuses until it becomes `ACTIVE`. The core statuses follow this path:`CREATED` → `PROCESSING` → … → `READY_TO_ACTIVATE` → `ACTIVE` Below is an example of the Alviere Portal showing three different Non-Reloadable Prepaid Debit Cards in various statuses (i.e., `PROCESSING`, `READY_TO_ACTIVATE` and `ACTIVE`). The card `status` field will change in the Portal as the card advances through the various stages in Production but in Sandbox, the card cannot advance through all the Statuses automatically since the system is not connected to external production environments. ### Simulate activation of a card To simulate what will occur in a production environment requires a few extra API calls. Here is how to advance the card to make it `ACTIVE`: 1. Open PostMan and navigate to **Import** 2. Click on the **Raw Text** menu option 3. Copy and paste the cURL details below to advance the card status from `PROCESSING` to `READY_TO_ACTIVATE`. The `card_uuid` field should be updated with the card you want to advance to the next processing stage. 4. Click **Import** on the next screen 5. Click the **Send** button 6. A successful update will result in a response of `200 Success` 7. To activate the card, use the `Activate Card` endpoint. Note: the last 4 and the expiration date can be obtained in the Portal by going to the Cardholder’s Issued Card section, locating the card and clicking the “eye” under Actions. A successful response will not have an error message displayed. ```plaintext curl --location --request POST 'https://mock.snd.alviere.com/shipCard' \ --header 'Content-Type: application/json' \ --data-raw '{ "card_uuid": "94fdd7cf-9c8c-4996-a852-4dda59153568" }' ``` **Notes:** * This step is **NOT needed** in production. * The steps above outline the process using Postman but you can use any utility to execute these requests. * Before this cURL can be issued the card status has to be in either `SET_TO_EMBOSS` or `PROCESSING`. If the card status is `CREATED` the process above will not work. ### Simulate swiping a card Now that the card is active you can use the SwipeCard request to generate a card transaction. **Note:** This step is **NOT needed** in production. The steps below outline the process using Postman but you can use any utility to execute these requests. 1. Open PostMan and navigate to **Import** 2. Click on the ‘**Raw Text**’ menu option 3. Copy and paste the cURL details below to simulate swiping a card and click Continue 4. Click **Import** on the next screen. ```plaintext curl --location --request POST 'https://mock.snd.alviere.com/swipeCard' \ --header 'Content-Type: application/json' \ --data-raw '{ "card_uuid": "b053ccd1-6f93-46c2-8384-68d4a040ca08", "amount": 199, "mcc": "5697", "merchant_name": "My Test Store", "merchant_id": "234575675" }' ``` 5. Update the card\_UUID with your card and the amount with the transaction value 6. Click the **Send** button 7. A successful update will result in a response of `200 Success` 8. You can see below the transaction is shown in Portal with the Status = `PROCESSING_PAYMENT` #### Request attributes | Attribute | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------------------------------------------- | | `card_uuid` | string | Yes | The UUID of the active issued card to swipe | | `amount` | number | Yes | The transaction amount | | `mcc` | string | No | Merchant Category Code for the simulated merchant. Must be a valid MCC | | `merchant_name` | string | No | Name of the simulated merchant | | `merchant_id` | string | No | Identifier of the simulated merchant | #### Default behavior for merchant attributes The three merchant attributes are optional. When omitted, the mock service applies consistent defaults: | You provide | The service does | | ------------------------- | ----------------------------------------------------------------------------------------------------- | | `mcc` and `merchant_name` | Uses both exactly as provided | | `mcc` only | Keeps your `mcc` and derives a merchant name consistent with that category | | `merchant_name` only | Keeps your merchant name and assigns a random valid `mcc` (a name cannot be reverse-mapped to a code) | | Neither | Assigns a random, consistent (`mcc`, `merchant_name`) pair | | No `merchant_id` | Assigns a predefined default merchant ID | ### Simulate different Card Brands During the card creation process for Card Issuance Create Card , you can create cards from different brands. The table below outlines the conditions that should be used to create cards from different brands. | Test Conditions | Card Brand created | | -------------------- | ------------------ | | firstName = "Mestre" | MASTERCARD | | firstName = "Vision" | VISA | | firstName = "Baymax" | AMEX | | firstName = "DISCO" | DISCOVERY | ### Shipping address variations When a physical card is shipped, it is possible that the post office will return the card to the sender. To simulate returned mail you can use the following data attributes when submitting a `Create Card` request. | Test Conditions | Card Status | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | Shipping Address:- `line_1` equals `703 Lisbon Ave` - `postal_code` starts with `71762` - `state` equals `AR` or - `line_1` equals `124 Main st` - `postal_code` starts with `99901` - `state` equals `AK` or - `line_1` equals `567 Park Ave` - `postal_code` starts with `36535` - `state` equals `AL` | RETURNED\_MAIL | ## Card and Bank Processing ### Card payment methods #### Test cards In order to test different card scenarios, our sandbox environment requires the use of a known and valid card number therefore we provide various test cards for your use. In addition, we provide the ability to simulate transaction failures and delays. The following sections outline what we have available for your use. We provide various test cards for various scenarios for your use. You can use the Payment methods `Create Card` endpoint to create a card payment method. Note: Even though our Sandbox Environment is not connected to external services, you should never use a real card number. | Card Number | Card Network | Card Sub-network | | ---------------- | ------------ | ---------------- | | 4111111111111111 | VISA | CREDIT | | 4000000760000002 | VISA | DEBIT | | 4001370077777777 | VISA | PREPAID | | 6011000990139424 | DISCOVER | CREDIT | | 6011111111111117 | DISCOVER | DEBIT | | 6011000991300009 | DISCOVER | PREPAID | | 371449635398431 | AMEX | CREDIT | | 378282246310005 | AMEX | DEBIT | | 378734493671000 | AMEX | PREPAID | | 5403879999999997 | MASTERCARD | CREDIT | | 5152537170792358 | MASTERCARD | DEBIT | | 5105105105105100 | MASTERCARD | PREPAID | #### Unhappy path statuses | Status | Test conditions | | --------- | ------------------------------------------------------------------------- | | `DELETED` | Use the "Delete card" API endpoint | | `FAILED` | Create a card with a zip code of less than 5 digits or more than 9 digits | #### 3D-S scenarios | Test data | Test outcome | | ----------------------------- | --------------------------------------------------------------------------------- | | Transaction amount: `$69.31` | Transaction `status` equals `FAILED`, `status_reason` equals `3DS_NOT_ENROLLED` | | Transaction amount: `$81.45` | Transaction `status` equals `FAILED`, `status_reason` equals `3DS_SYSTEM_ISSUE` | | Transaction amount: `$81.46` | Transaction `status` equals `FAILED`, `status_reason` equals `3DS_ERROR` | | Transaction amount:`$39.87` | Transaction `status` equals `FAILED`, `status_reason` equals `3DS_AUTH_EXPIRED` | | Transaction amount: any other | Transaction `status` equals `PENDING`, `status_reason` equals `3DS_AUTH_REQUIRED` | ### Bank payment methods ##### Unhappy path statuses | Status | Test conditions | | --------- | ----------------------------------------------------- | | `DELETED` | Use the "Delete bank account" API endpoint | | `FAILED` | Create a bank account using an invalid routing number | ### Simulate an ACH Return An ACH return reverses a previously originated transaction (for example, insufficient funds or a closed account). Use this to test how your integration handles returned transactions end-to-end —the simulated return file is processed through the same flow as in production. **Note:** This step is **NOT needed** in production. ```plaintext curl --location --request POST 'https://mock.snd.alviere.com/generateReturn' --header 'Content-Type: application/json' --header 'x-api-key: ' --data-raw '{ "transaction_uuid": "f84a40dd-3fbc-4478-bf89-ca5b30a95272", "return_code": "R01" }' ``` A successful request returns `204 No Content`. The return is processed asynchronously; the\ transaction will reflect the return shortly after. #### Request attributes | Attribute | Type | Required | Description | | ------------------ | ------ | -------- | -------------------------------------- | | `transaction_uuid` | string | Yes | The UUID of the originated transaction | | `return_code` | string | Yes | The ACH return reason code to simulate | #### Supported return codes | Code | Meaning | | ----- | ----------------------------------------- | | `R01` | Insufficient funds | | `R02` | Account closed | | `R03` | No account / unable to locate account | | `R04` | Invalid Account Number | | `R06` | Returned per ODFI Request | | `R08` | Payment Stopped | | `R16` | Account Frozen | | `R20` | Non-Transaction Account | | `R29` | Corporate customer advises not authorized | #### Eligible transaction types `LOAD_FUNDS`, `PAYMENT`, `WITHDRAW_FUNDS`, `BANK_DEBIT` #### Errors | Status | Condition | | ------ | -------------------------------------------------------------------------- | | `400` | Missing attribute, unsupported return code, or ineligible transaction type | | `404` | Transaction not found | | `409` | Transaction has already been returned | ### Simulate an ACH Notification of Change (NOC) A Notification of Change is distinct from a return: it does **not** reverse funds. It is a\ notice from the receiving bank telling the originator that something about the account should be corrected for future entries (for example, a new account or routing number). Use this to test how your integration handles RDFI-issued corrections. ```plaintext curl --location --request POST 'https://mock.snd.alviere.com/generateNoc' --header 'Content-Type: application/json' --header 'x-api-key: ' --data-raw '{ "transaction_uuid": "f84a40dd-3fbc-4478-bf89-ca5b30a95272", "change_code": "C01", "corrected_data": "987654321" }' ``` A successful request returns `204 No Content`. The NOC is processed asynchronously through the same flow as in production. #### Request attributes | Attribute | Type | Required | Description | | ------------------ | ------ | -------- | ----------------------------------------------------------- | | `transaction_uuid` | string | Yes | The UUID of the originated transaction | | `change_code` | string | Yes | The ACH change code describing what should be corrected | | `corrected_data` | string | Yes | The corrected value (e.g. the new account number for `C01`) | **Note:** `corrected_data` is passed through as-is; the mock service does not validate its format\ against the change code. #### Supported change codes | Code | Meaning | | ----- | -------------------------------------------------------------- | | `C01` | Incorrect account number | | `C02` | Incorrect routing number | | `C03` | Incorrect routing number and account number | | `C05` | Incorrect transaction code | | `C06` | Incorrect account number and transaction code | | `C07` | Incorrect routing number, account number, and transaction code | | `C13` | Addenda format error | #### Eligible transaction types `LOAD_FUNDS`, `PAYMENT`, `WITHDRAW_FUNDS`, `BANK_DEBIT` (same eligibility rules as ACH returns) ## International transfers For international transfers, the following test scenarios are supported. #### Fail Scenarios | Test data | Test outcome | | --------------------------------------- | ------------------------------------ | | Transaction amount: `$5.00` or `$10.00` | Transaction `status` equals `FAILED` | ##### Bank payout :Bank transfer failed after pushing the funds * **Requirements:** * Funding method -> `CASH`: destination amount must be `10000` or `20000` for both MXN and COP currencies (in USD: `$5.0` or `10.0`, for a default exchange rate of `0.05`). * **Outcome:** After 15 seconds (this period is ONLY for testing purposes) the `INTERNATIONAL_TRANSFER` will become `FAILED` due to failure to transfer. A `REFUND` transaction will be created in status `PENDING`, with status\_reason `REQUIRES_REFUND_METHOD`. The `refund_method` parameter needs to be set via the refund transaction endpoint thereafter for the refund to be processed correctly. ##### Cash payout : Beneficiary Fails to Collect Funds * **Requirements:** * Funding method -> `CASH`: destination amount must be `10000` or `20000` for both MXN and COP currencies (in USD: `$5.0` or `10.0`, for a default exchange rate of `0.05`). * **Outcome:** After 15 seconds (this period is ONLY for testing purposes) the `INTERNATIONAL_TRANSFER` will remain in `COMPLETED`. A `REFUND` transaction will be created in status `PENDING`, with status\_reason `REQUIRES_REFUND_METHOD`. The `refund_method` parameter needs to be set via the refund transaction endpoint thereafter for the refund to be processed correctly. #### Cancellation scenarios The Sandbox environment allows clients to simulate and test different scenarios for canceling international transfers. Below are the flows you can test, along with the required conditions for each: ##### Bank payouts ##### 1. Canceling a Transaction Within the 30-Minute Period * **Description:** This is the default behavior. Transactions can be canceled as long as the 30-minute cancellation window has not expired. * **Outcome:** The transaction is successfully canceled. ##### 2. Canceling a Transaction After the 30-Minute Period (Cancellation accepted) * **Requirements:** * Funding method -> `WALLET`, `BANK_PM`, `CARD_PM`: destination amount must be one of (`7600` || `13100`) for both MXN and COP currencies (in USD: `$3,80` or $`6,55`, for an default exchange rate of `0,05`). This will allow the transaction to be canceled successfully. * Funding method -> `CASH`: any amount can be used for this scenario. * **Outcome:** The transaction is successfully canceled, even though the 30-minute window has elapsed. ##### 3. Canceling a Transaction After the 30-Minute Period (Cancellation rejected) * **Requirements:** * The destination amount must be `13140` (in `MXN` or `COP`). * Equivalent to `$6.57` USD, assuming a default exchange rate of `0.05`. * **Outcome:** The cancellation request is rejected by the payout provider. ##### Cash pickups ##### 1. Cancellation Happy Path * **Requirements:** * Funding method -> `WALLET`, `BANK_PM`, `CARD_PM`, `CASH`: destination amount must be one of (`7600` || `13100`) for both MXN and COP currencies (in USD: `$3.80` or `$6.55`, for a default exchange rate of `0.05`). This will allow the transaction to be canceled successfully. * **Outcome:** The transaction is successfully canceled ##### 2. Cancellation Request Rejected – Cash Not Picked Up by Beneficiary * **Requirements:** * Funding method -> `WALLET`, `BANK_PM`, `CARD_PM`, `CASH`: destination amount must be `13140` cents in MXN/COP (in USD: `$6.57` for an exchange rate of `0.05`). * **Outcome:** Cancellation request is rejected (API returns 400). ##### Scenario 3: Cancellation Request Rejected – Cash Already Picked Up * **Requirements:** * Funding method -> `WALLET`, `BANK_PM`, `CARD_PM`, `CASH`: destination amount must be any amount **outside** of the following list: `7500`, `7600`, `11160`, `13000`, `13100`, `13140`, `10000`, `20000`. * **Outcome:** Cancellation request is rejected (API returns 400). ## Cash Loading When a cash load transaction is initiated, it flows through various statuses. The core statuses follow this path: `CREATED`→ `PROCESSING_PAYMENT`→ `COMPLETED` In the Sandbox environment, cash load transactions are simulated since the system is not connected to external production environments. The mock service allows you to test the cash load functionality using barcodes. #### Simulate Cash Load with Barcode To simulate what will occur in a production environment, follow these steps using Postman or any API client: 1. Open Postman and navigate to **Import** 2. Click on the **Raw Text** menu option 3. Copy and paste the cURL details below to simulate a cash load transaction 4. Update the `barcode_uuid` with your generated barcode via the create barcode API and set the desired `amount` 5. Click **Import** on the next screen 6. Click the **Send** button 7. A successful update will result in a response of `200 Success` ```plaintext curl --location 'https://mock.snd.alviere.com/cashloadWithBarcode' \ --header 'Content-Type: application/json' \ --data '{ "barcode_uuid": "f84a40dd-3fbc-4478-bf89-ca5b30a95272", "amount": 123.12 }' ``` #### To simulate a successful cash load transaction, follow these steps: 1. Ensure your barcode UUID is valid and hasn't been used before, and belongs to a `CHECKING` wallet 2. Set an amount that meets the minimum requirement ($5 USD) 3. Send the request as shown in the example above #### Example Transaction Response After a successful cash load, you can retrieve the transaction details which will look like this: ```json { "transaction": { "transaction_uuid": "776b2949-ac18-4238-98db-e1482207bc8f", "wallet_uuid": "6bff373e-f376-4af7-872a-8520756767e5", "account_uuid": "6bff373e-f376-4af7-872a-8520756767e5", "external_id": "db6e0e7d-e323-4258-8ce5-18090209d525", "transaction_type": "CASH_LOADING", "status": "COMPLETED", "description": "", "amount": 200, "currency": "USD", "type_details": { "payments_details": { "cash_loading": { "cash_loading_location": { "store_network_id": "7805446fa58cb76d059c828c3c0bda49", "store_name": "Dollar General", "terminal_id": "terminal-000", "barcode_data" : "1234567890" } } } }, "refunded": false, "disputed": false, "created_at": "2025-05-20T09:30:20.440433Z", "updated_at": "2025-05-20T09:30:20.440433Z", "metadata": { "customer_id": "CUST-83643", "device_id": "DEV-353", "transaction_id": "c3a30ab1-3649-4f66-8c3e-dfc105e428ff" } } } ``` #### To simulate a failed cash load transaction, follow these steps: 1. Use a barcode UUID which was used before 2. Set an amount that meets the minimum requirement ($5 USD) 3. Send the request as shown in the example above #### Example Transaction Response After the operation, you can retrieve the transaction details which will look like this: ```json { "transaction": { "transaction_uuid": "776b2949-ac18-4238-98db-e1482207bc8f", "wallet_uuid": "6bff373e-f376-4af7-872a-8520756767e5", "account_uuid": "6bff373e-f376-4af7-872a-8520756767e5", "external_id": "db6e0e7d-e323-4258-8ce5-18090209d525", "transaction_type": "CASH_LOADING", "status": "FAILED", "description": "", "amount": 200, "currency": "USD", "type_details": { "payments_details": { "cash_loading": { "cash_loading_location": { "store_network_id": "7805446fa58cb76d059c828c3c0bda49", "store_name": "Dollar General", "terminal_id": "terminal-000", "barcode_data" : "1234567890" } } } }, "refunded": false, "disputed": false, "created_at": "2025-05-20T09:30:20.440433Z", "updated_at": "2025-05-20T09:30:20.440433Z", "metadata": { "customer_id": "CUST-83643", "device_id": "DEV-353", "transaction_id": "c3a30ab1-3649-4f66-8c3e-dfc105e428ff" } } } ``` ## Transaction Fraud checks For transactions subjected to fraud checks during the authorization stage, specific amounts may lead to varying outcomes in the approval process for these transactions. The outcomes can be seen described below: | Test data | Test outcome | | ------------------------------------------------------------------ | ------------------------------------------- | | Consumer email domain: `@example.com` Transaction amount: `$33.34` | Transaction `status` equals `MANUAL_REVIEW` | | Consumer email domain: `@example.com` Transaction amount: `$33.35` | Transaction `status` equals `FAILED` | The transactions suitable for testing this workflow include the following: * `LOAD_FUNDS` * `INTERNATIONAL_TRANSFER` * `CARD_ISSUED_INITIAL` * `WITHDRAW_FUNDS` * `BANK_DEBIT` * `PAYMENT` * `WALLET_TRANSFER` * `CHECK_DEPOSIT` ## Transaction Sanctions checks For transactions subjected to sanctions checks during the authorization stage, specific amounts may lead to varying outcomes in the approval process for these transactions. The outcomes can be seen described below: | Test data | Test outcome | | --------------------------- | ------------------------------------------- | | Transaction amount: `$5.56` | Transaction `status` equals `MANUAL_REVIEW` | The transactions suitable for testing this workflow include the following: * `INTERNATIONAL_TRANSFER` * `BANK_DEBIT` to local Beneficiaries # Plaid Plaid helps people to securely connect and share data from their financial institutions with the apps and platforms. They allow it by providing their client SDK, Plaid Link, that abstracts and eases the process. Plaid Link SDK is a quick and secure way to link bank accounts to Plaid from within your app. It’s a drop-in component that your users will interact with in order to link their bank accounts. Plaid Link will handle credential validation, multi-factor authentication, and error handling for each institution that Plaid supports. LinkKit is a drop-in framework that handles connecting a financial institution to your app without passing sensitive information to the Alviere platform. On this guide you find useful links and advice to common integration scenarios within your app as well as steps that you need to take in order to have it correctly integrated with the Alviere platform. ### Setup Before writing code using the Plaid Link SDK, you must first perform some setup steps to register your app with Plaid, through the Alviere platform, and configure your project. #### Web Setup The first step to setup Plaid on your website is to create a redirect URI that is typically the address of a blank web page you'll need to create and host. This web page will be used to allow the end user to resume and complete the Link flow after completing the OAuth flow on their bank's website or app (for example ). After you set up the redirect URI path for Plaid you must provide it to an Alviere representative so it can be configured on your account. After you’ve completed this step you can start integrating the Plaid Link that is available from Plaid. You can follow the steps to do it on [Plaid official documentation](https://plaid.com/docs/link/web/#installation) where you can choose to integrate through the **vanilla JavaScript** library or the **React** one. #### Mobile Setup ##### iOS The first step to setup the Plaid Link SDK is to have universal links configured for your iOS application as Plaid uses it to handle the bank institutions that use OAuth as an authentication method. If you have universal links already setup for your application you just need to specify a path for Plaid (for example [_https://app.example.com/plaid_](https://app.example.com/plaid)). If you don’t have universal links already setted up you can follow [Plaid’s documentation](https://plaid.com/docs/link/ios/#set-up-universal-links) on it that covers how to set it up and configure the path _/plaid_. After you set up the universal link path for Plaid you must provide it to an Alviere representative so it can be configured on your account. When you finish the setup you can advance to the Plaid Link SDK installation. Plaid offers multiple ways to integrate their SDK on iOS, so you can choose to do it by Swift Package Manager (SPM), CocoaPods or Manually. You can follow the steps to integrate the SDK on [Plaid official documentation](https://plaid.com/docs/link/ios/#installation). You don’t need to do the final step about camera support as Alviere will not have it enabled. ##### Android Before you even start to install and configure the Plaid Link SDK you should provide your app package name to an Alviere representative so it can be configured on your account. After you’ve completed this step you can start installing the Plaid Link SDK that is available from Plaid as a Maven package. You can follow the steps to do it on [Plaid official documentation](https://plaid.com/docs/link/android/#add-the-plaidlink-sdk-to-your-app). You don’t need to do the final step about identity verification as Alviere will not have it enabled. ##### React Native Before starting to integrate with the Plaid Link React Native SDK you need to set up the platform-specific requirements (iOS and Android). For **iOS**, you need to have **universal links** configured for your application as Plaid uses it to handle the bank institutions that use OAuth as an authentication method. Please follow the instructions on how to specify a universal link on the **native iOS setup section** and then you just need to provide it to an Alviere representative so it can be configured on your account. For **Android**, you should provide your app package name to an Alviere representative so it can be configured on your account. After you finish the setup of the platform-specific requirements you can advance to the Plaid Link SDK installation. You can follow the steps to integrate the SDK on [iOS Plaid official documentation](https://plaid.com/docs/link/react-native/ios-setup/#ios-setup) (through CocoaPods or manually) and [Android Plaid official documentation](https://plaid.com/docs/link/react-native/android-setup/#add-plaidpackage-to-your-application). ### Linking an account In order for users to be able to link their bank accounts with the Alviere platform through Plaid they need to integrate what is shown on the diagram below. The first step to link an account should be to get a fresh [Plaid token from the Alviere API](https://apidocs.alviere.com/docs/api/af25d9cb8f169-request-a-plaid-token) (1). The token is needed to instantiate and launch the Plaid Link SDK and it’s the only piece of data that you need to open it. To set up the result callbacks and open the Plaid Link SDK on each platform/framework (2) please check Plaid official documentation below: * [Web](https://plaid.com/docs/link/web/#create) * [iOS](https://plaid.com/docs/link/ios/#create-a-configuration) * [Android](https://plaid.com/docs/link/android/#create-a-linktokenconfiguration) * [React Native](https://plaid.com/docs/link/react-native/#plaidlink) After presenting to the user the Plaid Link UI and authenticates and chooses the bank account that wants to link with success, the Plaid Link SDK will return on the _onSuccess_ callback (3) the linked account data. On that callback you should capture the _result.publicToken_ and [_result.account.id_](http://result.account.id) values that then should be used to link a Plaid bank account on the Alviere platform (4). To link the Plaid bank account you can either call the [Alviere API](https://apidocs.alviere.com/docs/api/925c76fb66cec-create-plaid-bank-account) directly or use the Alviere mobile Payments SDK: * [iOS Payments SDK](https://developer.alviere.com/sdk/ios/payments/#create-plaid-bank-account) * [Android Payments SDK](https://developer.alviere.com/sdk/android/payments/#create-plaid-bank-account) After this step the user bank account is successfully linked to the Alviere platform through the Plaid link SDK. #### OAuth Flow Some bank institutions (eg. Chase) requires the user to authenticate with OAuth on the device native browser or on the bank mobile app. With the OAuth authentication the users temporarily leave the app to authenticate and authorize data sharing using the bank institution's website or mobile app instead. Afterward, they're redirected back to the app to complete the Link flow. The only difference on the flow, when comparing with the main one, is that the mobile app will direct the users outside the app for authentication and then back but this is all managed by the Plaid Link SDK and no additional setup is required. The process to request the Plaid token at the beginning and the linking of the bank account at the end requires no additional changes too. ### Updating an Account Update mode is used to update authentication or authorization for a bank. This scenario is represented on the Alviere API through a Bank with `PENDING` status and a `NEEDS_UPDATE` status reason. The most common reason for this is when access to an existing bank stops working: if the user changes a password, if the multi-factor authentication (MFA) requirements change, or if the login becomes locked. Before opening the Plaid Link SDK for the user to update the bank account you need to request a fresh [Plaid token from the Alviere API](https://apidocs.alviere.com/docs/api/af25d9cb8f169-request-a-plaid-token) (1). This token request is the same as the one used to link a bank account but this time you need to provide the Alviere `payment_method_uuid` that identifies the user bank account on the Alviere platform. In this scenario, the token is an update token and when you instantiate and launch the Plaid Link SDK it will already be in the update mode. You just need to launch the Plaid Link SDK (2) the same way you do for linking an account. After presenting to the user the Plaid Link update UI and the user re-authenticates the bank account you just need to notify the Alviere platform that the bank account was updated. This can be done through the [Alviere API](https://apidocs.alviere.com/docs/api/13dd0920f77f3-activate-plaid-bank-account) directly or use the Alviere mobile Payments SDK: * [iOS Payments SDK](https://developer.alviere.com/sdk/ios/payments/#activate-plaid-bank-account) * [Android Payments SDK](https://developer.alviere.com/sdk/android/payments/#activate-plaid-bank-account) After this step the user bank account should be activated again and the status should change to `ACTIVE` on the Alviere platform. ### Testing the Implementation After you set up and integrate the linking of a bank account with the Alviere platform through the Plaid Link library you may want to test if it’s working correctly. To do that you can use the Alviere _sandbox_ environment which is compatible with the Plaid sandbox environment. This means that you can use the [Plaid testing credentials](https://plaid.com/docs/sandbox/test-credentials/) to simulate a wide range of scenarios within your app before promoting it to production. # Early Release of Funds Traditionally, all mobile check and ACH deposits follow the “good funds” model. This model mandates a waiting period before the settlement of deposits. While this model is effective in safeguarding against fraud, it inadvertently imposes a waiting period for customers to access their funds. This delay can be particularly challenging for those living paycheck to paycheck, who may need immediate access to their funds. As a result, there’s an increased likelihood of these customers seeking alternative financial services. The "Early Release of Funds" feature is designed to alleviate the challenges posed by the waiting period in the "good funds" model. This feature will empower your end customers to: 1. **Release deposited funds earlier** than the standard timeframe set by the good funds model. 2. **Develop custom business rules** to determine the eligibility and timing for early fund release. #### Key benefits * **Enhanced Customer Experience**: Customers gain quicker access to their funds, reducing financial strain and improving overall satisfaction. * **Reduced Dependency on Alternative Financial Services**: Early access to funds means customers are less likely to seek external financial solutions, such as check cashing services. * **Balanced Security and Convenience**: While accelerating fund availability, the feature maintains a strong stance against fraud. ### How it works: API integration The Early Release of Funds feature is seamlessly integrated into our API, allowing for a straightforward and efficient process. Below is a breakdown of how a typical request to release funds early would work using the "/transactions/release" API endpoint. #### API request example To initiate the Early Release of Funds, a POST request is sent to the "/transactions/release" endpoint. Here is an example of the request body: { "external\_id": "1AS245CHK", "transaction\_uuid": "3a6bcbed-b7dc-4791-84fe-b20f12be4001", "release\_amount": 1000, "service\_fees": \[ { "external\_id": "string", "description": "string", "calc\_type": "DEDUCT", "category": { "release\_fee": { "value": { "amount": 1000 } } } } ] } #### Request parameters * **external\_id**: A unique identifier for the transaction, provided by the program. * **transaction\_uuid**: The universally unique identifier (UUID) of the transaction in our system. * **release\_amount**: The amount of funds to be released early. This is represented in the smallest unit of the currency (e.g., cents for USD). * **service\_fees**: An array of service fee objects that might be applicable to the transaction. Each object includes: * **external\_id**: An identifier for the service fee. * **description**: A brief description of the service fee. * **calc\_type**: The calculation type for the fee, e.g., "DEDUCT" indicates that the fee should be deducted from the transaction amount. For releses, only "DEDUCT" is supported. * **category**: Specifies the category of the fee, For releases, only "release\_fee", along with its value. #### Fund release mechanism The "Early Release of Funds" feature operates by adjusting the fund allocations within a user's Wallet entity. Specifically, it involves transferring funds from one 'bucket' to another within the Wallet's `funds` object. Here's how it works: 1. **Pending Bucket**: Initially, funds from MCD and ACH deposits are placed in the `pending` bucket. This is where they remain during the standard waiting period as per the 'good funds' model. 2. **Transit Bucket**: When a request for early release of funds is approved, the specified amount is moved from the `pending` bucket to the `transit` bucket. This transfer signifies that the funds are now accessible to the customer, albeit not yet settled. #### Spending the released funds Once the funds are in the `transit` bucket, they are effectively available for the customer to use. Here's the process that follows when these funds are spent: 1. **Consumer Spending**: When the consumer decides to spend the funds, the transaction is initiated from the Wallet. 2. **Prefunding Treasury Vault**: If the funds in the `balance` bucket are not sufficient to cover the transaction, additional funds are temporarily sourced from the `prefunding` Treasury Vault. 3. **Settlement and Reconciliation**: Eventually, when the funds are settled, any temporary coverage provided by the `prefunding` treasury vault is reconciled. #### Ensuring smooth transactions * **Automated Transfers**: The movement of funds between these buckets is automated, ensuring a seamless experience for the customer. * **Real-time Updates**: The Wallet entity is updated in real-time to reflect the current state of the funds across different buckets. ### Decision-making process for funds release The decision to release funds early is critical and requires a careful evaluation of the risk involved. One of the key factors in this process is the assessment of the funding instrument used in transactions, particularly for `CHECK_DEPOSIT` and `LOAD_FUNDS` transaction types. The Transaction entity provides detailed information about the funding instrument, which is pivotal in the decision-making process. #### Funding Instrument Funding instruments represent the bank account information or other financial instrument used to pay for a transaction such as a check or load. The Transaction entity's `funds_source` contains the `funding_instrument_details` object, which encapsulates the following information: * **Funding Instrument token**: Each funding instrument is identified by a unique token (`funding_instrument_uuid`). This identifier helps in recognizing if the funding source is trusted and has been previously verified. This UUID is not just a marker of the instrument within a single financial program but is shared across all programs enabled by our platform. The shared nature of the UUID facilitates the pooling and sharing of fraud intelligence across different programs, enhancing our capability to detect and mitigate fraud on a broader scale. These tokens are created as soon as a new Payor is identified in the system in relation to a relevant transaction. * **Bank account information**: Beyond the UUID, the funding instrument object encapsulates bank account details (`bank_account_details`) including the routing and bank account numbers. This enables the identification of transactions linked to known bank accounts, particularly those associated with trusted third parties. #### Utilizing transactional summary data To further refine the decision-making process, the platform offers the capability to analyze transactional history through the _Calculate transactional summary data_ endpoint. This functionality allows for a detailed examination of an account's or funding instrument's transaction history by providing insights into: * The number of returned transactions * Completed and failed transactions * Total and average returned value Accessing this data requires submitting the `account_uuid` or `funding_instrument_uuid`, enriching the decision framework with quantitative metrics on transactional behavior. #### Implementing decision criteria The decision to release funds early should be based on a multifaceted assessment strategy: 1. **Trusted funding instruments**: The recognition of a funding instrument as trusted, underpinned by its UUID and bank account information, further corroborated by cross-program fraud intelligence, can trigger an instant release of funds. 2. **Known third-party payors**: Favorable consideration could also be given to transactions involving bank accounts of verified third parties. 3. **Transactional behavior**: The aggregated transactional data, reflective of an instrument's or account's historical activity, plays a crucial role in evaluating the risk and determining fund release eligibility. # BANK\_DEBIT #### Definition The `BANK_DEBIT` transaction type signifies the action of debiting funds from an Account's Wallet and transferring them to an external bank account owned by a designated beneficiary, or as a result of a direct debit from merchants. This type of transaction enables customers to move funds from their internal wallet to external bank accounts, thereby connecting the platform's internal financial environment with external banking systems. #### Prerequisites for Transaction creation For the creation of a transaction in the system, it is mandatory that the involved wallet and account are in an `ACTIVE` status, and that there are enough funds to cover the transaction amount and any associated service fees. If the transaction involves a Beneficiary, it will need to be of type `LOCAL` and be in status `ACTIVE`. #### Transaction status The `BANK_DEBIT` transaction supports the following statuses: | Status | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `CREATED` | The transaction has been initialized in the system, serving as the inception point. | | `PROCESSING_PAYMENT` | The transaction has been processed successfully and the system is waiting for funds settlement. | | `COMPLETED` | Funds have successfully settled. | | `FAILED` | The transaction couldn't process, typically due to payment rejection, like a declined card transaction. | | `ERROR` | A system glitch or anomaly that hindered the transaction's processing. | | `MANUAL_REVIEW` | This status signifies that the transaction is undergoing a thorough review by Alviere's compliance and risk department. | | `CANCELED_SYSTEM` | An automated system rule resulted in the transaction's cancellation. | | `REJECTED` | After manual scrutiny, the transaction was declined by the risk and fraud department. | #### Status reason This transaction does not support status reasons at present. # CARD\_ISSUED\_DISPUTE\_DEBIT ## Definition The `CARD_ISSUED_DISPUTE_DEBIT` transaction represents the reversal of a provisional credit (`CARD_ISSUED_DISPUTE_CREDIT`) that was previously awarded to an Alviere-issued cardholder. This transaction occurs when a dispute is resolved against the cardholder's favor. The purpose of this transaction is to debit the Account's Wallet, removing the provisional credit that was initially granted during the dispute process for a `CARD_ISSUED_DEBIT`transaction. ### Transaction status The `CARD_ISSUED_DISPUTE_DEBIT` transaction supports the following statuses: | Status | Description | | ----------- | ------------------------------------------------------------------------------- | | `COMPLETED` | Confirms that the funds have been successfully debited from the Account Wallet. | ### Status reason This transaction does not support status reasons at present. # CARD\_ISSUED\_DISPUTE\_CREDIT ## Definition The `CARD_ISSUED_DISPUTE_CREDIT` transaction represents the provisional credit awarded to an Alviere-issued cardholder when they dispute any `CARD_ISSUED_DEBIT` transaction. The purpose of this transaction is to award a temporary credit to the cardholder's account while a dispute is being investigated. This provisional credit ensures that the cardholder has access to the disputed funds during the investigation process. ### Transaction status The `CARD_ISSUED_DISPUTE_CREDIT` transaction supports the following statuses: | Status | Description | | ----------- | ---------------------------------------------------------------------------- | | `COMPLETED` | Confirms that the funds have been successfully placed in the Account Wallet. | ### Status reason This transaction does not support status reasons at present. # CARD\_ISSUED\_TERMINAL\_CREDIT ## Definition The `CARD_ISSUED_TERMINAL_CREDIT` transaction represents the loading of cash through physical store locations when the load is tied to an Alviere issued card through the VisaReadyLink networks. ### Transaction status The `CARD_ISSUED_TERMINAL_DEBIT` transaction supports the following statuses: | Status | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PROCESSING_PAYMENT` | This status indicates that the transaction authorization request has been received from our provider. The system is currently processing the payment. Money can be used the the cardholder now. | | `CANCELED_SYSTEM` | This status indicates that the transaction was canceled. Reason could range from Merchant initiated cancellations to customer requests. | | `COMPLETED` | This status indicates that the transaction has been successfully settled or reversed. If we received a reversal request from the network, a child transaction `REVERSAL` will be created in the ledger as well. | ### Status reason This transaction does not support status reasons at present. ### Service Fees When a `CARD_ISSUED_TERMINAL_CREDIT` transaction is initiated, the associated `SERVICE_FEE` transactions follow these rules: ##### During Authorization: * `SERVICE_FEE` status: CREATED * Parent transaction (`CARD_ISSUED_TERMINAL_CREDIT`) status: `PROCESSING_PAYMENT` ##### Transaction Outcomes: 1. If parent transaction (`CARD_ISSUED_TERMINAL_CREDIT`) is canceled: 1. Parent status: `CANCELED_SYSTEM` 2. `SERVICE_FEE`transactio status: `CANCELED_SYSTEM` 3. A `REVERSAL` transaction entry is created in the ledger with status `CANCELED_SYSTEM` 4. Result: Service fees are not charged 2. If parent transaction (`CARD_ISSUED_TERMINAL_CREDIT`) is completed but reversed after: 1. Parent status: `COMPLETED` (with a child `REVERSAL` transaction) 2. `SERVICE_FEE` status: `COMPLETED` 3. Result: Service fees are charged 4. Note: Service fees can be reversed using the provided endpoint `Reverse transaction` The `SERVICE_FEE` transaction mirrors the status of its parent transaction (`CARD_ISSUED_TERMINAL_CREDIT`) in cases of cancelation or reversal. # CHECK\_DEPOSIT ## Definition This transaction type is used to denote the deposit of digital check into an Account Wallet. ### Prerequisites for Transaction creation For the creation of a transaction in the system, it is mandatory that the involved wallet and account are in an `ACTIVE` status. ### Transaction status The `CHECK_DEPOSIT` transaction supports the following statuses: | Status | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------- | | `CREATED` | Marks the beginning of the transaction in the system. | | `PROCESSING` | Indicates the check has cleared initial security checks and is currently being processed. | | `PROCESSING_PAYMENT` | Signifies approval from the compliance department; the payment process with the bank is underway. | | `COMPLETED` | Confirms that the funds have been successfully transferred to the Account Wallet. | | `FAILED` | Denotes rejection of the check due to fraud or compliance concerns. | | `ERROR` | Indicates the check was declined by an automated risk detection system. | | `CANCELED_USER` | Reflects cancellation of the check by a fraud detection agent. | | `MANUAL_REVIEW` | The transaction is under detailed review by the Compliance and Fraud department. | | `CANCELED_SYSTEM` | An automated system rule resulted in the transaction's cancellation. | | `REJECTED` | The transaction has been officially declined following a manual review by the Compliance and Fraud department. | ### Status reason The `status_reason` will be inherited from the Check entity that is associated with this `CHECK_DEPOSIT` transaction. For a list of Check status reasons, please refer to the [Check](../hive-definitions/check.md) section in this guide. # INTERNATIONAL\_TRANSFER ### Definition The `INTERNATIONAL_TRANSFER` Transaction type is designed to handle and record the movement of funds across international borders. ### Prerequisites for Transaction creation For the creation of a transaction in the system, it is mandatory that the involved wallet and account are in an `ACTIVE` status, and that there are enough funds to cover the transaction amount and any associated service fees. The related Beneficiary will need to be of type `INTERNATIONAL`, be in status `ACTIVE` and contain an active Payout Method. #### Transaction Purpose The `transaction_purpose` field determines the valid reasons for initiating an international transfer through our API. The table below outlines the accepted purposes by country and transaction type. #### Legend: * **P2P** - Person-to-Person * **P2B** - Person-to-Business * **B2P** - Business-to-Person * **B2B** - Business-to-Business | **Purpose** | **Canada** | **Hong Kong** | **India** | **Philippines** | | -------------------------------------- | ----------- | --------------- | ----------- | --------------- | | `FAMILY_MAINTENANCE` | P2P B2P | P2P B2P | P2P | P2P | | `EDUCATION` | P2P P2B B2P | P2P P2B B2P | P2P P2B B2P | P2P P2B B2P | | `MEDICAL` | P2P P2B B2P | P2P P2B B2P | P2P P2B B2P | P2P P2B B2P | | `TOURIST` | | | P2P P2B B2P | | | `PERSONAL` | | P2P | P2P B2P | | | `BUSINESS` | P2B B2B | P2B B2B | | P2B B2B | | `INVESTMENT` | P2B B2B | P2B B2B | | P2B B2B | | `TRADES` | P2B B2B | P2B B2B | | P2B B2B | | `TRANSFER_TO_NRE_ACCOUNT` | | | P2P B2P | | | `INVESTMENT_IN_MUTUAL_FUND_INSURANCE` | | | P2B | | | `INVESTMENT_THROUGH_BANK` | | | P2B | | | `PURCHASE_OF_REAL_ESTATE` | | | P2P P2B B2P | | | `EDUCATION_TUITION_BOARDING` | | | P2P P2B B2P | | | `HOTEL_ACCOMMODATIONS` | | P2B B2B | P2B | | | `TRAVEL_AGENT` | | P2P P2B B2P B2B | P2P P2B B2P | P2P P2B B2P B2B | | `UTILITY_PROVIDER` | | | P2B | | | `TAX_PAYMENT` | | P2B B2B | P2B | P2B B2B | | `LOAN_PAYMENT_TO_BANK` | | | P2B | | | `PRIME_MINISTERS_NATIONAL_RELIEF_FUND` | | | P2B | | | `HOSPITAL_OR_MEDICAL_INSTITUTION` | | | P2P P2B B2P | | | `PAYMENT_FOR_SERVICE` | | | | P2P P2B B2P B2B | | `PAYMENT_FOR_GOODS` | | | | B2B P2B | | `TRADE_RELATED_SERVICES` | | P2B B2B | P2B B2P | | | `TRADE_REALISATION_OF_EXPORT_BILLS` | | P2B B2B | P2B | | | `TRADE_ADVANCE_RECEIPT_AGAINST_EXPORT` | | P2B B2B | P2B | | #### Source of funds The `source_of_funds` field determines the valid The source of funds for the transaction. This field can only be sent in specific corridors . Allowed values are `EMPLOYMENT_INCOME`,`OWNED_BUSINESS`,`FAMILY_INCOME`,`SAVINGS`,`INVESTMENTS`,`INHERITANCE`, `PROCEEDS_OF_SALE`,`PENSION` . ### Transaction status The `INTERNATIONAL_TRANSFER` transaction supports the following statuses: | Status | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `CREATED` | The transaction has been initialized in the system, serving as the inception point. | | `PROCESSING` | At this stage, the transaction is in the midst of processing, typically when a ledger transaction necessitates a payment action. | | `PROCESSING_PAYMENT` | The transaction has been authorized and the funds are being transferred to the international financial institution. | | `COMPLETED` | Funds have settled into the international financial institution. | | `FAILED` | The transaction couldn't process, typically due to payment rejection, like a declined card transaction. | | `ERROR` | A system glitch or anomaly that hindered the transaction's processing. | | `CANCELED_USER` | The transaction was halted either by a customer or an agent via the Portal. | | `CANCELED_SYSTEM` | An automated system rule resulted in the transaction's cancellation. | | `MANUAL_REVIEW` | This status signifies that the transaction is undergoing a thorough review by Alviere's compliance and risk department. | | `PENDING` | The transaction is waiting for some action from the end customer. Currently only applicable in flows that require 3D-S authentication. | | `REJECTED` | After manual scrutiny, the transaction was declined by the risk and fraud department. | ### Status reason `INTERNATIONAL_TRANSFER` transactions can present a status reason if a failure occurs due to issues with the payment method utilized for funding the transaction, and will inherit the reason from the corresponding child passthrough transaction, namely `CARD_PASSTHROUGH` and `BANK_PASSTHROUGH`. Possible `status_reason` values for these transactions are equivalent to the ones applicable to the `LOAD_FUNDS` transaction type.Other possible status reasons are below: Here is the updated markdown table with the items in the first column enclosed in backticks: | **Status Code** | **Description** | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `ACCOUNT_NUMBER_INCORRECT` | The Payout method account number is incorrect or invalid. | | `ACCOUNT_CLOSED` | The Beneficiary's account has been closed. | | `NON_PAYMENT_ACCOUNT` | The Beneficiary's account is not eligible to receive payments. | | `ACCOUNT_DETAILS_INCORRECT` | Incorrect or invalid Payout method account details provided for the transaction. | | `ACCOUNT_NAME_NO_MATCH_RECEIVER` | The account name does not match the Beneficiary’s name. | | `INTERNAL_ERROR` | A system error occurred within the service provider's system. | | `AMOUNT_INCORRECT` | The transaction amount is incorrect or invalid. | | `BANK_NAME_INCORRECT` | The bank name provided for the transaction is incorrect. | | `BENEFICIARY_ID_INCORRECT` | The Beneficiary's identification is incorrect or invalid. | | `BENEFICIARY_NAME_INCORRECT` | The Beneficiary's name does not match the provided details. | | `BENEFICIARY_TRANSACTION_LIMIT_EXCEEDED` | The Beneficiary has exceeded their transaction limit. | | `BRANCH_INCORRECT` | The branch details provided are incorrect or invalid. | | `COMPLIANCE_RELATED` | The transaction failed due to compliance regulations or checks. | | `CORRESPONDENT_LIMIT_EXCEEDED` | The correspondent bank's limit has been exceeded for this transaction. | | `IBAN_INCORRECT` | The International Bank Account Number (IBAN) is incorrect or invalid. | | `BANK_CODE_INCORRECT` | The bank code provided for the transaction is incorrect. | | `PAYOUT_METHOD_INACTIVE` | The selected payout method is not currently active. | | `TRANSACTION_EXPIRED` | The transaction has expired and can no longer be processed. | | `BENEFICIARY_MINOR` | The Beneficiary is a minor and ineligible to receive the transaction. | | `MISSING_DOCUMENTS` | Required documents for the transaction are missing. | | `REFUND_REQUESTED` | A refund has been requested for the transaction. | | `SANCTIONED_BANK_COUNTRY` | The transaction is blocked due to sanctions against the beneficiary's country. | | `ACCOUNT_ADDRESS_INCORRECT` | The address provided for the account is incorrect or invalid. | | `3DS_AUTH_REQUIRED` | The end customer needs to go through the 3D-S authentication flow in order to authorize the transaction. | | `3DS_NOT_ENROLLED` | The card is not 3D Secure (3D-S) enabled. | | `3DS_AUTH_FAILED` | Cardholder failed 3DS authentication. | | `3DS_AUTH_EXPIRED` | Initial 3DS transaction not completed within 15 minutes. | | `3DS_SYSTEM_ISSUE` | 3DS system malfunction. | | `3DS_AUTH_REQUIRED` | 3DS authentication required. | | `3DS_ERROR` | 3DS authentication service provided invalid authentication result. | # LOAD\_FUNDS ## Definition The `LOAD_FUNDS` transaction type is utilized to represent the action of loading money into an account wallet through external payment methods, including both card and bank accounts. ### Transaction status The `LOAD_FUNDS` transaction supports the following statuses: | Status | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `CREATED` | Marks the beginning of the transaction in the system. | | `PROCESSING_PAYMENT` | Signifies approval from the compliance department; the payment process with the bank is underway. | | `COMPLETED` | Confirms that the funds have been successfully loaded into the Account Wallet. | | `FAILED` | The transaction couldn't process, typically due to payment rejection, like a declined card transaction, or an automated risk detection system. | | `ERROR` | A system glitch or anomaly that hindered the transaction's processing. | | `CANCELED_USER` | Reflects cancellation of the transaction by a fraud detection agent. | | `CANCELED_SYSTEM` | An automated system rule resulted in the transaction's cancellation. | | `MANUAL_REVIEW` | The transaction is under detailed review by the Compliance and Fraud department. | | `VOIDED` | The transaction was nullified before the actual payment execution, ensuring no debit or credit on the payment method. | | `REJECTED` | The transaction has been officially declined following a manual review by the Compliance and Fraud department. | ### Status reason ##### FAILED status (Bank Payment Method) For `LOAD_FUNDS` Transactions in `FAILED` status, when the funds are loaded from a Bank Payment Method, the following `status_reasons` are supported: | Status Reason | Description | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NOT_SUFFICIENT_FUNDS` | Insufficient funds in the external bank account when performing a funds balance check | | `NOT_SUFFICIENT_FUNDS_RECHECK` | Insufficient funds in the external bank account when performing a funds balance recheck for fraud prevention | | `ERROR_RECHECK` | Error when performing when performing a funds balance recheck for fraud prevention | | `NOT_AUTHORIZED_DUE_TO_PREVIOUS_RETURN` | Previous transaction(s) returned, causing authorization failure for current transaction | | `INVALID_PUBLIC_TOKEN` | Public token used for transaction is invalid or expired | | `INVALID_ACCESS_TOKEN` | Access token for external bank account is invalid or expired | | `INVALID_ACCOUNT_ID` | The account ID of the external bank account is incorrect or unrecognized | | `EXCHANGE_TOKENS_UNMAPPED` | Failure in mapping exchange tokens during the transaction process | | `INVALID_BANK_ACCOUNT` | The bank account details provided are invalid or do not match with the external bank | | `ITEM_NOT_SUPPORTED` | The external bank account or its features are not supported by the platform | | `ITEM_LOCKED` | The external bank account is temporarily locked or restricted | | `ITEM_NO_VERIFICATION` | The external bank account could not be verified for the transaction | | `TOO_MANY_VERIFICATION_ATTEMPTS` | Exceeded the number of allowed verification attempts for the external bank account | | `NO_ACCOUNTS` | No external bank accounts are linked or available for the transaction | | `NO_AUTH_ACCOUNTS` | No valid checking or savings account(s) for which account and routing numbers could be retrieved | | `NO_INVESTMENT_ACCOUNTS` | No valid investment account(s) for which holdings or transactions could be retrieved | | `ACCOUNT_NOT_FOUND` | The specified external bank account was not found | | `LAST_UPDATED_BALANCE_OUT_OF_RANGE` | The last updated balance of the external bank account is outside the permissible range for the transaction | | `AVAILABLE_FUNDS_BELOW_REQUIREMENTS` | The transaction could not be authorized because we were unable to verify the account's balance. Additionally, the most recent balance information we have indicates that the funds in the account fall short of the minimum required by our risk assessment model | | `BALANCE_RATE_LIMIT_EXCEEDED` | The frequency of balance inquiries for the external bank account has exceeded the platform's limits | | `OTHER` | The failure reason is not specifically identified or mapped | ##### FAILED status (Card Payment Method) For `LOAD_FUNDS` Transactions in `FAILED` status, when the funds are loaded from a Card Payment Method, the following `status_reasons` are supported: | Status Reason | Description (Revised) | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `BANK_DECLINE` | Transaction declined by the issuing bank | | `INVALID_MERCHANT_OR_PROVIDER` | Merchant or provider involved in the transaction is invalid or unrecognized | | `AUTHORIZATION_DECLINED` | Authorization for the transaction was declined | | `OTHER` | Failure reason not specified or falls under miscellaneous | | `REQUEST_IN_PROGRESS` | The transaction request is still being processed | | `PARTIAL_APPROVAL` | Transaction partially approved, indicating partial or incomplete transfer | | `INVALID_TRANSACTION` | Transaction is invalid due to errors in transaction details or format | | `INVALID_AMOUNT` | The amount specified in the transaction is invalid or incorrect | | `INVALID_ACCOUNT_NUMBER` | The account number of the card is invalid or unrecognized | | `CUSTOMER_CANCELLATION` | Transaction cancelled by the customer | | `CUSTOMER_DISPUTE` | Transaction disputed by the customer | | `FORMAT_ERROR` | Error in the transaction format or data | | `PARTIAL_COMPLETION` | Transaction only partially completed | | `NO_CREDIT_ACCOUNT` | No credit account associated with the card available for the transaction | | `NO_INVESTMENT_ACCOUNT` | No investment account available for the transaction | | `INSUFFICIENT_FUNDS` | Insufficient funds available in the card's account | | `NO_CHECKING_ACCOUNT` | No checking account associated with the card available for the transaction | | `NO_SAVINGS_ACCOUNT` | No savings account associated with the card available for the transaction | | `CARD_EXPIRED` | The card used for the transaction has expired | | `NO_CARD_RECORD` | No record of the card found in the system | | `TRANSACTION_NOT_PERMITTED_TO_CARDHOLDER` | Transaction type not permitted for the cardholder | | `SUSPECTED_FRAUD` | Transaction flagged as suspected fraud | | `CARD_ACCEPTOR_CONTACT_ACQUIRER` | Card acceptor needs to contact the acquirer | | `MAX_ACTIVITY_AMOUNT_LIMIT` | Transaction amount exceeds the card's maximum activity limit | | `RESTRICTED_CARD` | The card is restricted and cannot be used for the transaction | | `SECURITY_VIOLATION` | Transaction flagged due to security concerns | | `EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT` | Transaction exceeds the card's withdrawal frequency limit | | `RESPONSE_LATE` | Late response in processing the transaction | | `CARD_NOT_ACTIVE` | The card used is not active or has not been activated for use | | `CVV2_FAILURE` | Failure in verifying the card's CVV2 code during the transaction | | `PIN_REQUIRED` | Transaction requires the card's PIN, which was not provided or incorrect | | `DAILY_AMOUNT_LIMIT` | Transaction exceeds the card's daily amount limit | | `EXCEEDS_TRANSACTION_LIMIT` | Transaction exceeds the card's transaction limit | | `CARD_NOT_SUPPORTED` | The card type or network is not supported by the platform | | `UNSUPPORTED_CURRENCY` | The currency involved in the transaction is not supported | | `MERCHANT_TRANSACTION_LIMIT` | Transaction exceeds the merchant's transaction limit | | `3DS_NOT_ENROLLED` | Card not enrolled in 3D Secure for the transaction | | `3DS_AUTH_FAILED` | 3D Secure authentication failed during the transaction | | `3DS_AUTH_EXPIRED` | 3D Secure authentication expired prior to transaction completion | | `3DS_SYSTEM_ISSUE` | Issue encountered with the 3D Secure system | | `3DS_AUTH_REQUIRED` | 3D Secure authentication is required for the transaction | | `3DS_ERROR` | Error occurred during 3D Secure processing | | `PICK_UP_CARD` | Notification to retrieve the card, usually due to suspected fraud or security issues | | `ISSUER_NOT_FOUND` | The issuer of the card could not be identified or found | | `MAX_AMOUNT_LIMIT` | Transaction exceeds the maximum amount limit set by the card issuer | | `ISSUER_DECLINED` | Transaction declined by the card issuer for unspecified reasons | | `MAX_PIN_RETRY_LIMIT_FRAUD` | Exceeded the maximum PIN entry attempts, suspected fraud | | `LOST_CARD_FRAUD` | Transaction attempted with a card reported lost | | `STOLEN_CARD_FRAUD` | Transaction attempted with a card reported stolen | | `AMLD5` | Transaction declined due to Anti-Money Laundering Directive 5 compliance issues | | `CLOSED_ACCOUNT` | Transaction attempted with a card linked to a closed account | | `BLACKLIST` | The card or cardholder is blacklisted, preventing transaction completion | | `REFER_TO_ISSUER_FRAUD` | Transaction flagged as potentially fraudulent. Contact the card issuer for further verification. | | `REFER_TO_ISSUER` | The card issuer must be contacted for further details or authorization. | | `INVALID_MERCHANT` | Merchant is not recognized or authorized by the card network. | | `CARD_STOLEN_FRAUD` | Transaction attempted with a card reported as stolen. Immediate blocking and investigation required. | | `DO_NOT_HONOR` | The card issuer declined the transaction without providing further details. | | `ERROR` | A general error occurred in the transaction processing, requiring a retry or further investigation. | | `PICK_UP_CARD_FRAUD` | The card is suspected to be compromised and should be retained by the merchant. | | `HONOR_WITH_IDENTIFICATION` | Transaction requires identity verification of the cardholder to proceed. | | `APPROVED_FOR_PARTIAL_AMOUNT` | Only a partial amount of the transaction was approved by the card issuer. | | `INVALID_CARD_NUMBER` | The provided card number is invalid or does not match any card issuer. | | `RE_ENTER_TRANSACTION` | Transaction needs to be entered again due to an error or miscommunication. | | `INVALID_RESPONSE` | The response from the card network was invalid or incomplete. | | `NO_ACTION_TAKEN` | The requested action was not taken, possibly due to a previously processed transaction. | | `SUSPECTED_MALFUNCTION` | A technical malfunction suspected, preventing transaction completion. | | `UNACCEPTABLE_TRANSACTION_FEE` | The transaction fee exceeds the allowed limit by the card issuer or network. | | `FILE_UPDATE_NOT_SUPPORTED` | The requested file update operation is not supported by the system. | | `RECORD_NOT_FOUND_ON_FILE` | The requested record for the transaction could not be found. | | `DUPLICATE_FILE_UPDATE` | A duplicate file update request was detected and rejected. | | `FILE_UPDATE_FIELD_ERROR` | An error in one of the fields in the file update request was detected. | | `FILE_UPDATE_RECORD_LOCKED` | The record intended for update is locked and cannot be updated at the moment. | | `FILE_UPDATE_NOT_SUCCESSFUL` | Update attempt to the file containing card data was unsuccessful, possibly due to system error or network issues. | | `BANK_NOT_SUPPORTED` | The bank associated with the card is not supported by the payment network or merchant's system. | | `COMPLETED_PARTIAL` | The transaction was only partially completed, possibly due to insufficient funds or credit limit restrictions. | | `CARD_EXPIRED_FRAUD` | Transaction attempted with an expired card, suspected of fraud. | | `CARD_ACCEPTOR_CONTACT_ACQUIRER_FRAUD` | Merchant must contact the acquirer due to a suspicious transaction that could be fraudulent. | | `CARD_RESTRICTED_FRAUD` | Card has been restricted due to suspected fraudulent activities. | | `ACTION_NOT_SUPPORTED` | The requested action is not supported by the card, network, or issuer. | | `NO_UNIVERSAL_ACCOUNT` | No universal account number could be found or matched, typically in systems requiring cross-border compatibility. | | `ACCOUNT_CLOSED` | Transaction attempted on an account that has been previously closed. | | `NOT_SUFFICIENT_FUNDS` | Insufficient funds in the cardholder's account to complete the transaction. | | `PIN_INCORRECT` | The entered PIN does not match the PIN stored on record for the card. | | `CARD_NOT_FOUND` | The specified card number could not be found in the issuer's system. | | `TRANSACTION_NOT_PERMITTED` | The cardholder's account does not permit this type of transaction. | | `EXCEEDS_WITHDRAWAL_LIMIT` | The amount requested exceeds the withdrawal limit set for the card or account. | | `CARD_RESTRICTED` | The card has been restricted, possibly for security or administrative reasons. | | `ORIGINAL_AMOUNT_INCORRECT` | The amount initially authorized differs from the amount being charged. | | `CARD_ACCEPTOR_CALL_ACQUIRER_SECURITY` | Merchant must contact the acquirer due to security concerns potentially involving the transaction. | | `HARD_CAPTURE_FRAUD` | Card must be physically retained by the merchant due to suspected fraud. | | `EXCEEDS_PIN_RETRY_LIMIT` | The allowable number of PIN entry attempts has been exceeded, triggering a security response. | | `KEY_SYNCHRONIZATION_ERROR` | There was an error in synchronizing the encryption keys used in the transaction. | | `POS_NOT_ELIGIBLE` | The Point of Sale terminal used is not eligible for this transaction, possibly due to settings or network restrictions. | | `LIFECYCLE_DECLINES` | Transaction declined due to the card being at a lifecycle stage that does not permit the transaction (e.g., expired, not activated). | | `STALE_DATED_TRANSACTION` | Transaction attempted with a date that is no longer valid or too old as per issuer's policies. | | `ISSUER_REQUESTED_STANDIN` | Issuer's systems are possibly down, and a stand-in authorization is requested, but not possible. | | `FRAUD_SECURITY` | Transaction flagged for security review due to potential fraud indicators or violation of security protocols. | | `EXCEEDS_PRE_AUTH_TIME_LIMIT` | Transaction exceeds the time limit set for completing a transaction following a pre-authorization. | | `ISSUER_HAS_NO_REASON` | Issuer declined the transaction without providing any specific reason. | | `PIN_NOT_VERIFIED` | The entered PIN could not be verified as correct by the card issuer or network. | | `CHECK_ALREADY_POSTED` | A transaction similar to the current one has already been processed and posted. | | `INFORMATION_NOT_ON_FILE` | Required information for processing the transaction is missing from the issuer's records. | | `INVALID_CVV` | The Card Verification Value (CVV) entered is incorrect or invalid. | | `CUTOFF_IN_PROGRESS` | Transaction attempted during a processing cutoff period, typically end of day or batch processing time. | | `ISSUER_OR_SWITCH_INOPERATIVE` | The card issuer or payment switch is temporarily inoperative or under maintenance. | | `NETWORK_UNKNOWN` | The transaction was sent to an unrecognized network, or there's an error identifying the network. | | `LAW_VIOLATION` | Transaction stopped due to a suspected violation of law or regulation. | | `DUPLICATE_TRANSACTION` | The same transaction has been submitted more than once. | | `RECONCILE_ERROR` | An error occurred during the reconciliation process, possibly due to mismatched transaction details. | | `SYSTEM_MALFUNCTION` | A general system malfunction occurred, preventing the transaction from being processed. | | `RESERVED_FOR_NATIONAL_USE` | Code reserved for specific national use cases, not applicable or unrecognized in the current context. | | `CARD_NETWORK_FAULT` | A failure or fault has been detected in the card network, affecting transaction processing. | | `NETWORK_ISSUE` | General network-related issues preventing successful transaction processing. | | `INVALID_OR_UNSUPPORTED_SEC` | Security measures required for the transaction are invalid or not supported by the current system setup. | | `AVS_DATA_REQUIRED` | Address Verification Service (AVS) data was not provided but is required for processing the transaction. | | `CVV2_DATA_REQUIRED` | Card Verification Value (CVV2) is required but was not provided or was incorrect. | | `ISSUER_COUNTRY_BLOCKED` | The transaction is blocked because the issuer's country is on a blocked list. | | `INCORRECT_MAC` | Message Authentication Code (MAC) was incorrect, suggesting a data integrity issue. | | `STANDARD_ENTRY_CLASS_REQUIREMENTS` | The transaction does not meet the standard entry class requirements, often related to batch processing rules. | | `SYSTEM_TIME_OUT` | The transaction could not be processed in time, leading to a timeout. | | `ACCOUNT_LENGTH_ERROR` | The provided account number does not meet the required length for processing. | | `CHECK_DIGIT_ERROR` | The check digit for the account number is incorrect, failing validation. | | `CID_FORMAT_ERROR` | Card Identification Number (CID) format is incorrect or invalid. | | `AUTHORIZATION_EXPIRED` | The authorization for the transaction has expired before completion. | | `CARD_PRODUCT_CODE` | The card product code does not match the transaction type or is not supported. | | `BRIC_PIN_TRANSACTION_MISMATCH` | There is a mismatch between the transaction and the BRIC (Biometric Risk Identification Code) PIN data. | | `CYBERCOURCE_TIMEOUT` | Transaction processing timed out specifically on the CyberSource payment gateway. | | `MISSING_INFORMATION` | Essential information required for processing the transaction is missing. | | `INVALID_CARD` | The card number is not valid or does not exist. | | `PIN_BLOACK_NOT_PRESENT` | The required PIN block was not present in the transaction data. | | `BIN_MISSING_FOR_PINLESS_ROUTING` | The BIN necessary for routing the pinless transaction is missing. | | `SIGNATURE_STORE_INCOMPLETE` | The signature required to complete the transaction was not fully captured or stored. | | `SWIPE_FOR DEBIT_PIN` | Error in swipe data processing for a debit transaction requiring PIN verification. | | `DB_TIMEOUT` | Database timeout occurred, preventing transaction completion. | | `MERCHANT_DECLINED` | The transaction was declined by the merchant, possibly due to policy or suspecting fraud. | | `GATEWAY_ROUTING_ERROR` | There was an error in routing the transaction through the payment gateway. | | `AUTHORIZATION_NOT_ACCEPTED` | The authorization provided was not accepted by the processing network or issuer. | | `ITEM_NOT_RECEIVED` | The transaction was flagged because the item or service was not received by the purchaser. | | `EXCEEDS_TRANSACTION_FLOOR_LIMIT` | The transaction amount exceeds the floor limit for transactions without additional authorization. | | `AUTHORIZATION_DECLINED` | The issuer declined the authorization request without specifying the reason. | | `ACCOUNT_NUMBERS_NOT_MATCHED` | The account number provided does not match any account on record. | | `ERROR_IN_ADDITION` | An addition error occurred in the transaction processing, possibly due to a computational or data entry error. | | `ALTERED_AMOUNT` | The amount authorized differs from the amount charged, suggesting alteration. | | `ACCOUNT_NUMBER_NOT_CORRECT` | The account number entered is incorrect or does not match the expected format. | | `SIGNATURE_MISSING` | A required signature for the transaction is missing, necessary for verification or authorization. | | `SLIP_NO_CARD_IMPRINT` | The transaction slip lacks a card imprint, required for physical verification in some manual transactions. | | `SLIP_MULTIPLE_CARD_IMPRINT` | Multiple card imprints on a single slip, indicating a potential error or fraud attempt. | | `PREAUTHORIZATION_CANCELED` | A pre-authorization was canceled before the transaction could be completed, possibly by the cardholder or issuer. | | `CURRENCY_CONVERSION_ERROR` | Errors occurred in converting currency values during the transaction processing. | | `CREDIT_POSTED_AS_DEBIT` | A transaction intended as a credit was processed as a debit, causing accounting errors. | | `CLAIM_OR_DEFENCE` | The transaction was disputed by the cardholder, initiating a claim or defense process. | | `NON_RECEIPT_OF_GOODS` | The goods or services were not received by the cardholder, leading to a transaction dispute. | | `DEFECTIVE_MERCHANDISE` | Goods received were defective, leading to a transaction dispute. | | `CARD_AUTHENTICATION_FAILED` | Failure in the card authentication process, possibly due to incorrect data or security breaches. | | `FRAUDULENT_TRANSACTION` | Transaction identified as fraudulent by systems or manual review. | | `MERCHANT_BLOCKED` | The merchant involved in the transaction has been blocked from processing payments due to compliance issues or fraud. | | `BAD_CVV3` | Incorrect CVV3 code entered, a security measure on the card that was not matched correctly. | | `UNKNOWN_ERROR` | An error occurred for which the cause is not specified or unknown. | | `CHECK_NOT_ACCEPTABLE_FOR_CASH` | A check presented for cashing was not acceptable, possibly due to issues with the check or bank policies. | | `CHECK_NOT_ACCEPTED` | The check used for the transaction was not accepted by the merchant or bank. | | `EXCEEDS_CHECK_DEPOSIT_LIMIT` | The amount of the check exceeded the deposit limit set by the bank or merchant. | | `EXCEEDS_CASHBACK_LIMIT` | The requested cashback exceeds the limit set by the merchant or bank. | | `CHECK_AMOUNT_COURTESY_AMOUNT` | The written and numerical amounts on a check do not match, commonly referred to as a courtesy amount error. | | `PIN_NOT_SELECTED` | The PIN for the transaction was not selected or set up by the cardholder. | | `PIN_ALREADY_SELECTED` | An attempt was made to select or change a PIN that had already been established. | | `UNMATCHED_VOUCHER` | The voucher presented does not match records or expected values for the transaction. | | `EXCEEDS_PAN_RETRY_LIMIT` | The number of allowed attempts to enter the card number (PAN) has been exceeded during the transaction. | | `WRONG_EXPIRATION` | The expiration date entered is incorrect or past due. | | `CARD_INACTIVE` | The card is inactive either due to not being activated or having been deactivated by the issuer. | | `WRONG_EXPIRATION_FRAUD` | Incorrect expiration date used as a potential fraud attempt. | | `ITEM_SUSPECTED_STOP_PAY` | A stop payment order suspected on an item involved in the transaction. | | `INELIGIBLE_AMOUNT` | The transaction amount is ineligible for processing under current policy or limits. | | `ITEM_SUBMITTED_MORE_THAN_TWO_TIMES` | The same item has been submitted for payment more than twice, indicating a possible error or fraud. | | `NO_ACCOUNT_ON_FILE` | No account was found corresponding to the information provided in the transaction. | | `UNABLE_TO_LOCATE` | The transaction details or related records could not be located in the system. | | `GENERAL_DENIAL` | A general denial without specific details, often used when specific error codes are not applicable. | | `SETTLED_VIA_ACH` | The transaction was settled through Automated Clearing House (ACH), not directly through card networks. | | `DELINQUENT_SETTLEMENT` | Settlement was delayed beyond the acceptable period, often leading to transaction failure. | | `CROSS_REFERENCE_CARD_NOT_FOUND` | The card details do not match any records in the cross-reference file, possibly due to a data mismatch or outdated information. | | `EXCEEDS_CATEGORY_LIMIT` | The transaction exceeds the spending limit set for a specific category of purchases. | | `EXCEEDS_DAILY_LIMIT` | The amount or number of transactions exceeds the daily limit set by the issuer or bank. | | `EXCEEDS_MONTHLY_LIMIT` | The transaction amount or count goes beyond the set monthly limit for the account. | | `INVALID_SECRET_CODE` | The secret code entered (like a PIN or a password) was invalid. | | `PIN_KEY_SYNC` | There is a synchronization issue with the PIN key, possibly due to technical errors in encryption or communication. | | `BAD_CVV2` | The CVV2 code entered was incorrect, failing security verification required for transaction processing. | | `STOP_PAYMENT_ORDER` | A stop payment order has been issued on this transaction or on the instrument used. | | `REVOCATION_OF_AUTHORIZATION` | The authorization previously granted for the transaction has been revoked by the cardholder or issuer. | | `STOP_REOCCURING_PAYMENTS` | Recurring payments have been stopped at the request of the cardholder or due to a policy violation. | | `CARD_LOST` | The transaction was declined because the card was reported lost. | | `DORMANT_ACCOUNT` | The account associated with the card is dormant due to inactivity, triggering security protocols that block transactions. | | `SPECIAL_CONDITION` | The transaction was flagged due to special conditions set on the account or card, requiring further checks or validation. | | `PURCHASE_ONLY_WITH_CASHBACK` | The transaction is permitted only if it includes a cashback component, otherwise, it's declined. | | `NOT_SUFFICIENT_FUNDS_FOR_FEES` | There are insufficient funds in the account to cover the fees associated with the transaction. | | `ARQC_VALIDATION_FAILED` | The transaction failed ARQC (Application Request Cryptogram) validation, indicating possible tampering or data corruption. | | `UNSAFE_PIN` | The PIN used is considered unsafe (e.g., too simple or compromised) and has triggered a security block. | | `MASTERCARD_EXPIRATION_DATE` | The transaction was declined because the MasterCard used has expired. | | `MASTERCARD_CARD_DECLINED` | MasterCard has declined the transaction for reasons not specified to the merchant. | | `MASTERCARD_BIN_NOT_SUPPORTED` | The BIN (Bank Identification Number) on the MasterCard is not supported by the processing network. | | `MASTERCARD_UNKNOWN_REASON` | The transaction was declined by MasterCard for an unknown reason, requiring further investigation. | | `MASTERCARD_UNKNOWN_STATUS` | The status of the transaction is unknown due to an issue with MasterCard's processing. | # WALLET\_TRANSFER ## Definition The `WALLET_TRANSFER` transaction type is used to record and manage peer-to-peer transfers of funds between two wallets that are part of the same financial program. This transaction can occur between different accounts or even within the same account, allowing for versatile and internal fund movements. ### Prerequisites for Transaction creation For the creation of a transaction in the system, it is mandatory that the involved wallets and accounts are in an `ACTIVE` status. Additionally, both wallets must be configured to handle the same currency type. #### Transaction status The `WALLET_TRANSFER` transaction supports the following statuses: | Status | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------- | | `PROCESSING_PAYMENT` | Transaction initial status pending fraud checks. | | `COMPLETED` | Confirms that the funds have been successfully transferred to the Account Wallet. | | `MANUAL_REVIEW` | The transaction is under detailed review by the Compliance and Fraud department. | | `CANCELED_SYSTEM` | An automated system rule resulted in the transaction's cancellation. | | `REJECTED` | The transaction has been officially declined following a manual review by the Compliance and Fraud department. | #### Status reason This transaction does not support status reasons at present. # Introduction Webhooks can be used to get events from Alviere. For example, when a transaction is settled, Alviere can send an event to your webhook consumer with information about the transaction. Events are grouped into **Subscriptions** and each Subscription event will be posted into a URL provided by you at the moment of the subscription. **Note:** Alviere sends all events asynchronously so that it doesn't block or slow down any system operation or transaction. All events are actions that already took place. ### Subscriptions Alviere provides several different subscriptions to receive different event types: * `ACCOUNT` provides information about the lifecycle of your program accounts. * `WALLET_TRANSACTION` provides information about the lifecycle of wallet transactions. * `ISSUED_CARD` provides information about the lifecycle of all cards issued by Alviere. * `BENEFICIARY` provides information about the lifecycle of all beneficiaries in your program. * `BANK_PM` provides information about the lifecycle of all bank accounts used as payment methods. * `CARD_PM` provides information about the lifecycle of all cards used as payment methods. * `CHECK` provides information about the lifecycle of check deposit transaction. * `DOSSIER` provides information about the lifecycle of all uploaded dossiers. ### Payload format ```json { "event_uuid": "082fd7f7-7e9e-4679-bd16-ed9f5a55d827", "program_uuid": "04d3ac6e-82d3-4f52-b82f-6cc0320928af", "event_date": "2021-06-17T11:02:08.143Z", "event_retry": 0, "event_type": [SUBSCRIPTION_TYPE], "event_version": "2021-11-18.1", "entity":{ ... } } ``` ### Authentication Each subscription requires the following information: * Subscription type * Target endpoint (needs to be a complete HTTPS URL) * Authentication method and credentials * Version required for each subscription ### **Authentication Methods** **Option 1: Header-Based Authentication (Default)** When we call your endpoint, we include a header called `Alviere-Auth` with the security key you provided to us. **Option 2: HMAC Signature Authentication** For enhanced security, you can use HMAC-SHA256 signature verification. Provide your shared secret to your implementation manager, and we'll sign each webhook payload. You can then verify the signature to ensure authenticity. When using HMAC authentication, webhooks include: * `Alviere-Signature` - HMAC-SHA256 signature of the payload * `Alviere-Webhook-Id` - Unique identifier for the webhook * `Alviere-Webhook-Timestamp` - Unix timestamp when sent To verify the signature: 1. Construct the payload: `..` 2. Calculate HMAC-SHA256 using your shared secret 3. Compare with the `Alviere-Signature` header value #### **HMAC Verification example:** **Go** ```go package main import ( "bytes" "crypto/hmac" "crypto/sha256" "encoding/hex" "encoding/json" ) func calculateHmac(requestBody []byte, alviereWebhookId, alviereWebhookTimestamp, sharedSecret string) (string, error) { // remove insignificant spaces (minify) bodyBuffer := new(bytes.Buffer) if err := json.Compact(bodyBuffer, requestBody); err != nil { return "", err } hmacInputBuffer := new(bytes.Buffer) hmacInputBuffer.WriteString(alviereWebhookId + "." + alviereWebhookTimestamp + ".") hmacInputBuffer.Write(bodyBuffer.Bytes()) hmacHash := hmac.New(sha256.New, []byte(sharedSecret)) hmacHash.Write(hmacInputBuffer.Bytes()) hmacSum := hmacHash.Sum(nil) return hex.EncodeToString(hmacSum), nil } ``` **Python** ```python import hashlib import hmac import json def calculate_hmac(request_body, alviere_webhook_id, alviere_webhook_timestamp, shared_secret): # remove insignificant spaces (minify) json_object = json.loads(request_body) \_body = json.dumps(json_object, separators=(',', ':')) hmac_input = alviere_webhook_id + "." + alviere_webhook_timestamp + "." + _body hmac_object = hmac.new(shared_secret.encode(), hmac_input.encode(), hashlib.sha256) return hmac_object.hexdigest() ``` **Node js** ```javascript import { createHmac } from 'node:crypto'; const requestBody = {key: 'value'}; const secret = 'hmac-secret'; const webhookId = 'alviere_webhook_id'; const timestamp = 'alviere_webhook_timestamp'; // remove insignificant spaces (minify) const body = JSON.stringify(requestBody); const getHmac = (secret, webhookId, timestamp, body) => { const hmac = createHmac('sha256', secret); hmac.update([webhookId, timestamp, body].join('.')); return hmac.digest('hex'); }; console.log(getHmac(secret, webhookId, timestamp, body)); ``` **Java** ```java import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.util.HexFormat; public class CalculateHmac { public static String hmacHex(String request_body, String alviere_webhook_id, String alviere_webhook_timestamp, String shared_secret) { String algorithm = "HmacSHA256"; // remove insignificant spaces (minify) request_body = minifyJson(request_body); try { SecretKeySpec secret_key = new SecretKeySpec(shared_secret.getBytes("UTF-8"), algorithm); Mac sha256_HMAC = Mac.getInstance(algorithm); sha256_HMAC.init(secret_key); String hmac_input = String.join(".", alviere_webhook_id, alviere_webhook_timestamp, request_body); return HexFormat.of().formatHex(sha256_HMAC.doFinal(hmac_input.getBytes("UTF-8"))); } catch (Exception e) { throw new RuntimeException("Failed to compute HMAC: " + e.getMessage(), e); } } public static String minifyJson(String jsonString) { StringBuilder result = new StringBuilder(); boolean inQuotes = false; for (int i = 0; i < jsonString.length(); i++) { char c = jsonString.charAt(i); if (c == '\"') { result.append(c); inQuotes = !inQuotes; } else if (!inQuotes && Character.isWhitespace(c)) { // skip } else { result.append(c); } } return result.toString(); } } ``` ### Processing Each time we send a message for the provided URL, we expect a `200` HTTP status code, otherwise we will retry the event applying a polynomial backoff starting at 20ms and going up to 2 minutes after each retry. **NOTE** that we will continuously retry sending the message and this will impact any other messages in the queue as we strictly maintain messages in order (FIFO). ### How to subscribe Please contact your implementation manager for more information. # Account Event You can subscribe the Account Webhook to receive all events that occur in accounts. The returned object will contain the account in the state at the moment of the event creation. For example, if there's a `status` change, you'll receive an event with the new status. #### Payloads for `ACCOUNT` Subscription Type ```json { "entity": { "account_uuid": "fab54d64-62d1-45ed-ac50-536c533fef19", "created_at": "2022-10-11T09:12:19.495Z", "external_id": "ea0d8bac-c395-4492-a831-06d980fa979f", "information": { "consumer_information": { "date_of_birth": "****-02-07", "email_address": "e**********l@example.org", "first_name": "Cin**ia", "last_name": "Wie**nd", "middle_name": "Re***l", "phone_number": "+*********7", "ssn_last_4": "9201" } }, "metadata": { "key_example": "example", "key_example_2": 10 }, "stage": "", "status": "ACTIVE", "status_reason": "string", "status_reason_description": "string", "type": "CONSUMER", "profile": "string", "profile_request": { "profile": "string", "status": "PROCESSING", "stage": "string", "status_reason": "string" }, "updated_at": "2022-10-11T09:12:37.548Z" }, "event_date": "2022-10-11T09:12:43.16Z", "event_retry": 0, "event_type": "ACCOUNT", "event_uuid": "a082a01e-637d-5bc3-9153-76246869f21a", "event_version": "2021-11-18.1", "program_uuid": "3ff8d46a-da4d-46f1-a296-db483914b896" } ``` # Bank payment method event You can subscribe the Bank payment method Webhook to receive all events that occur in a bank account associated to an Alviere account in the system. The returned object will contain the bank account in the state at the moment of the event creation. For example, if there's a `status` change, you'll receive an event with the data for the bank account. #### Payloads for `BANK_PM` Subscription Type ```json { "entity": { "account_uuid": "86e28f4b-c52d-4498-be89-a890b2298269", "bank_account_details": { "ach_details": { "account_number_last_4": "9012", "routing_number": "051000017" } }, "country": "USA", "created_at": "2022-10-11T09:09:31.283Z", "currency": "USD", "external_id": "7eb9e43f-dffd-48cf-ac8a-25e0590859d6", "fail_reason": "", "flags": { "load_supported": false, "withdraw_supported": true }, "is_plaid": false, "last_4": "9012", "payment_method_uuid": "502f5dcc-07d8-4801-a988-0d2ba67a8e35", "status": "DELETED", "status_reason": "", "type": "UNKNOWN", "updated_at": "2022-10-11T09:09:31.283Z" }, "event_date": "2022-10-11T09:11:47.958Z", "event_retry": 0, "event_type": "BANK_PM", "event_uuid": "db8e3589-3c4c-59ea-8b15-da1950e2916e", "event_version": "2021-11-18.1", "program_uuid": "3ff8d46a-da4d-46f1-a296-db483914b896" } ``` # Card payment method event You can subscribe the Card payment method Webhook to receive all events that occur in a card payment method associated to an Alviere account in the system. The returned object will contain the card in the state at the moment of the event creation. For example, if there's a `status` change, you'll receive an event with the data for the card. #### Payloads for `CARD_PM` Subscription Type ```json { "entity": { "account_uuid": "86e28f4b-c52d-4498-be89-a890b2298269", "payment_method_uuid": "09f46e1f-aa02-46ec-ae6d-34946f385e3d", "external_id": "string", "brand": "VISA", "type": "CREDIT", "country": "USA", "last_4": "0000", "status": "CREATED", "status_reason": "", "flags": { "load_supported": false, "withdraw_supported": false }, "3ds_options": { "3ds_preference": "ENABLED" }, "created_at": "string", "updated_at": "string" }, "event_date": "2022-10-06T08:24:26.577Z", "event_retry": 0, "event_type": "CARD_PM", "event_uuid": "7a525c30-57d7-5429-b260-53559609e5c2", "event_version": "2021-11-18.1", "program_uuid": "3ff8d46a-da4d-46f1-a296-db483914b896" } ``` # Beneficiary type event You can subscribe to the Beneficiary Webhook to receive all events that occur for Beneficiary entities. The returned object will contain the Beneficiary in the state at the moment of the event creation. For example, if there's a `status` change, you'll receive an event with the new status. #### Payloads for `BENEFICIARY` Subscription Type ```json { "entity": { "account_uuid": "86e28f4b-c52d-4498-be89-a890b2298269", "address": { "city": "W*******n", "country": "U**", "line_1": "91 ***********", "postal_code": "0***2", "state": "M*" }, "bank_account_details": { "clabe_details": { "bic_code": "CMFGUS33XXX", "clabe_number_last_4": "7771" } }, "beneficiary_uuid": "e2cdd74a-484e-478b-8c1e-edef95993c69", "country": "MEX", "created_at": "2022-10-11T09:11:21.459Z", "currency": "MXN", "date_of_birth": "", "external_id": "8b6813df-2136-463f-b402-bb2ac875804f", "first_name": "A**", "last_name": "Kau**er", "status": "ACTIVE", "status_reason": "", "type": "BENEFICIARY", "updated_at": "2022-10-11T09:11:32.188466205Z" }, "event_date": "2022-10-11T09:11:32.483Z", "event_retry": 0, "event_type": "BENEFICIARY", "event_uuid": "589ed560-1a14-55c1-97e3-63fe40dce312", "event_version": "2021-11-18.1", "program_uuid": "3ff8d46a-da4d-46f1-a296-db483914b896" } ``` # Check event You can subscribe the Check Webhook to receive all events that occur related to checks. The returned object will contain the check in the state at the moment of the event creation. For example, if there's a `status` change, you'll receive an event with the new status. #### Payloads for `CHECK` Subscription Type ```json { "entity": { "account_uuid": "86e28f4b-c52d-4498-be89-a890b2298269", "check_number": "", "check_uuid": "5cb572da-880a-4bd9-9668-28a22e7700c7", "created_at": "2022-10-06T08:24:14.763Z", "currency": "USD", "entered_amount": 10000, "external_id": "", "status": "PREVERIFIED", "status_reason" : "AMOUNT", "rejected_reasons" : ["INVALID_DOCUMENT", "AMOUNT"] "transaction_uuid": "490e9f00-094b-43fc-89e1-628430580cbc", "updated_at": "2022-10-06T08:24:22.503465894Z", "wallet_uuid": "253a481d-8664-403e-906b-d25d5963ca5e" }, "event_date": "2022-10-06T08:24:26.577Z", "event_retry": 0, "event_type": "CHECK", "event_uuid": "7a525c30-57d7-5429-b260-53559609e5c2", "event_version": "2021-11-18.1", "program_uuid": "3ff8d46a-da4d-46f1-a296-db483914b896" } ``` # Dossier event You can subscribe the Dossier Webhook to receive all events that occur in Dossiers. The returned object will contain the Dossier in the state at the moment of the event creation. For example, if there's a `status` change, you'll receive an event with the new status. #### Payloads for `DOSSIER` Subscription Type ```json { "entity": { "account_uuid": "18b0f633-8766-4223-adc7-e6c944f794b4", "created_at": "2022-10-01T03:59:51.006550614Z", "documents": [ { "type": "DRIVER_LICENSE_FRONT" }, { "type": "DRIVER_LICENSE_BACK" }, { "type": "SELFIE" } ], "dossier_uuid": "c97a2500-4e6a-4a97-b8e4-502ca0045556", "external_id": "3b525637-ac97-43ea-9697-c041444e3fcb", "primary": false, "status": "CREATED", "country_of_issuance": "USA", "status_reason": "", "updated_at": "2022-10-01T03:59:51.006550614Z" }, "event_date": "2022-10-01T03:59:51.251Z", "event_retry": 0, "event_type": "DOSSIER", "event_uuid": "7f4f5ed0-6306-5f81-b0e2-c8e22e5d9f6c", "event_version": "2021-11-18.1", "program_uuid": "291eecdb-0e55-4e5b-8e51-375bc173a2a9" } ``` # Issued Card event You can subscribe the Issued Card Webhook to receive all events that occur in a card issued by your program. The returned object will contain the Card in the state at the moment of the event creation. For example, if there's a `status` change, you'll receive an event with the new status. #### Payloads for `ISSUED_CARD` Subscription Type ```json { "entity": { "account_uuid": "86e28f4b-c52d-4498-be89-a890b2298269", "auth_rules": { "allowed_merchants": { "allowed_merchant_ids": [], "allowed_merchant_names": [] } }, "incentive_rules":[], "blocked": false, "brand": "MASTERCARD", "card_expiration": "10/27", "card_uuid": "9fc8c952-9dd5-48a7-a082-f9fee2dd6caa", "created_at": "2022-10-10T15:58:26.832966269Z", "custom_fields": { "name_on_card": "Zack Murphy", "shipping_method": "DEFAULT" }, "external_id": "43a5ed46-9405-49af-aa1f-87f6fbd99b34", "initial_balance": 0, "emboss_id":"", "last_4": "5925", "metadata": {}, "pin_set": false, "product_id": "26432", "service_fees": [], "shipping_address": { "city": "Watertown", "country": "USA", "line_1": "91 Langdon Ave", "line_2": "", "postal_code": "02472", "state": "MA" }, "status": "ACTIVE", "status_reason": "", "type": "DEBIT", "updated_at": "2022-10-10T15:58:27.182489614Z", "wallet_uuid": "01f4746a-a916-418e-8c9f-ecce3260622a" }, "event_date": "2022-10-10T15:58:30.126Z", "event_retry": 0, "event_type": "ISSUED_CARD", "event_uuid": "e50114b3-9865-5f3f-a6b0-f8f1f899f8e6", "event_version": "2021-11-18.1", "program_uuid": "3ff8d46a-da4d-46f1-a296-db483914b896" } ``` # Wallet transaction event You can subscribe the Wallet transaction Webhook to receive all events that occur in wallet transactions. The returned object will contain the Transaction in the state at the moment of the event creation. For example, if there's a `status` change, you'll receive an event with the new status. #### Payloads for `WALLET_TRANSACTION` Subscription Type ```json { "entity": { "account_uuid": "47584a74-ee3f-4245-b830-5463996794f4", "amount": -200, "beneficiary_uuid": "e2cdd74a-484e-478b-8c1e-edef95993c69", "currency": "USD", "description": "<random>", "external_id": "385f6f11-bf7c-4515-94b5-fd1a9cb4fcc8", "metadata": {}, "status": "CREATED", "status_reason": "", "transaction_type": "INTERNATIONAL_TRANSFER", "parent_transaction_uuid": "5acfa667-0956-4e69-b9a5-95e206e6ba32", "transaction_uuid": "9279ba1f-c2f3-48f2-96ea-ae479bca30fd", "type_details": { "global_payments_details": { "exchange_rate": "1.52233", "ready_for_collection": "2019-08-24T14:15:22Z", "collected_at": "2019-08-24T14:15:22Z" }, "issued_card_details": { "issued_card_uuid": "6dfd4f82-035f-4fba-aa55-2e5f16c1cee0", "merchant_name": "STARBUCKS", "merchant_id": "123456", "terminal_id": "00010102", "network": "VISA", "subnetwork": "INTERLINK", "is_international": true }, "payments_details": { "company_identification": "string", "company_name": "string", "cash_loading": { "cash_loading_location": { "store_network_id": "7805446fa58cb76d059c828c3c0bda49", "store_name": "Dollar General", "terminal_id": "terminal-000", "barcode_data": "1234567890" } }, "card_processing": { "auth_type": "string", "3ds_details": { "redirect_url": "string", "3ds_result": "string", "enrolled": true, "3ds_preference": "ENABLED" }, "merchant_details": { "name": "string", "address": { "line_1": "101 Avenue of the Americas", "line_2": "Suite 936", "postal_code": "10013", "city": "New York", "state": "NY", "country": "USA" }, "email_address": "string", "url": "string", "phone_number": "string" } } } }, "funds_source": { "origin_bank": "CHASE BANK", "is_payroll": true, "payroll_date": "2019-08-24", "account_verification": true, "payment_method_uuid": "5acfa667-0956-4e69-b9a5-95e206e6ba32", "check_uuid": "ed2fa4e3-2ec7-4b35-a804-6ba1d78b289d", "check_released_amount": "b223b145-3fdc-4ab5-9f2f-604bf4566072", "payment_instrument_uuid": "3b48d882-6438-46f0-bc7c-ab9069ce9294", "settled_at": "2019-08-24T14:15:22Z" }, "release_details": { "releasable_amount": 0, "releases": [ { "created_at": "2024-02-08T00:59:44.329971Z", "external_id": "622b6c1b-8c69-4de1-ac3c-d8da7431b064", "release_amount": 6740, "release_uuid": "f7c9127d-3b86-4031-9190-693277dccbbf" } ] }, "settled_at": "2019-08-24T14:15:22Z", "refunded": false, "refund_reason": "string", "disputed": true, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "transaction_options": { "payment_options": { "ACH_type": "SAME_DAY", "prefund": "string" } } }, "event_date": "2022-10-11T09:11:48.214Z", "event_retry": 0, "event_type": "WALLET_TRANSACTION", "event_uuid": "bb4e7d84-7979-4947-9e1f-29231ed0abaf", "event_version": "2021-11-18.1", "program_uuid": "3ff8d46a-da4d-46f1-a296-db483914b896" } ``` # Activity Event You can subscribe the Activity Webhook to receive all activities associated with the account ### Event Details **Event Type:** `ACTIVITY` **Supported Activity Types:** * `CARD_REPLACEMENT` * `DENIED_AUTHORIZATION` ### When to Use This Webhook **Use this webhook if you need:** * Real-time notifications when account-level activities occur * Updates for events like card replacement initiation or authorization denials #### Payloads for `CARD_REPLACEMENT` Type ```json { "business_account_uuid": "3ff8d46a-da4d-46f1-a296-db483914b896", "entity": { "activity_uuid": "example-activity-uuid", "account_uuid": "example-account-uuid", "wallet_uuid": "example-wallet-uuid", "entity_uuid": "example-entity-uuid", "entity_type": "ISSUED_CARD", "type": "CARD_REPLACEMENT", "type_details": { "card_replacement_details": { "reason": "example", "replacement_card_uuid": "example-replacement-card-uuid", "waive_fees": true, "description": "Customer reported the card as lost.", "waive_fees_reason": "Customer Loyalty", "waive_fees_description": "Fees waived as part of our customer loyalty program." } }, "event_date": "2022-10-11T09:11:48.214Z", "event_retry": 0, "event_type": "ACTIVITY", "event_uuid": "bb4e7d84-7979-4947-9e1f-29231ed0abaf", "event_version": "2021-11-18.1", "program_uuid": "3ff8d46a-da4d-46f1-a296-db483914b896" } ``` #### Payloads for `DENIED_AUTHORIZATION` Type ```json { "entity": { "activity_uuid": "7c2d6f6e-3b3c-4a41-9b26-a3f0d5c2e9ab", "account_uuid": "a1b2c3d4-e5f6-4789-ab01-23456789abcd", "wallet_uuid": "w1234567-89ab-4cde-f012-3456789abcde", "type": "DENIED_AUTHORIZATION", "type_details": { "denied_authorization_details": { "card_uuid": "c0ffee00-1234-4abc-9def-001122334455", "denied_reasons": [ "INSUFFICIENT_FUNDS" ], "amount": "23.45", "currency": "USD", "network": "VISA", "subnetwork": "BANKNET", "merchant_name": "ACME ONLINE STORE", "merchant_id": "M1234567890", "terminal_id": "T9876543210", "is_international": false } } }, "event_date": "2025-08-12T19:36:40Z", "event_retry": 0, "event_type": "ACTIVITY", "event_uuid": "f4863f42-061d-5f0a-ab8a-e8f25a35c4dd", "event_version": "2021-11-18.1", "program_uuid": "f874b26c-2dbd-487f-8994-f38605cfb0a5", "business_account_uuid": "ba-5c7e9a1b-2345-6789-abcd-ef0123456789" } ``` #### Payloads for `CARD_CREATED` Type ```json { "entity":{ "activity_uuid": "79f43a3a-f179-48ba-ae64-2e7c6eb6856f", "account_uuid": "fef9925a-1b26-451b-a902-f7e3fef62500", "wallet_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "entity_uuid": "9f66cd1a-6069-49ec-a977-a53301d1aee5", "entity_type": "ISSUED_CARD", "type": "CARD_CREATED", "type_details": { "card_created_details": { "card_uuid": "9f66cd1a-6069-49ec-a977-a53301d1aee5", "type": "DEBIT", "brand": "VISA", "genre": "VIRTUAL", "product_id": "virtual-debit-card" } }}, "event_date": "2025-08-12T19:36:40Z", "event_retry": 0, "event_type": "ACTIVITY", "event_uuid": "f4863f42-061d-5f0a-ab8a-e8f25a35c4dd", "event_version": "2021-11-18.1", "program_uuid": "f874b26c-2dbd-487f-8994-f38605cfb0a5", "business_account_uuid": "ba-5c7e9a1b-2345-6789-abcd-ef0123456789" } ``` # Overview * [Overview](#overview) * [1. Backend Authentication](#backend-authentication) * [2. Include Web SDK](#include-web-sdk) * [3. Instantiate SDK Service](#instantiate-sdk-service) * [4. Service (Payments)](#payments-service) * [5. Service (Fraud)](#fraud-service) * [6. Service (Card Issuance)](#card-issued-service) * [Version History (Changelog)](#version-history-changelog) * [Copyright and license](#copyright-and-license) ### Introduction * **Name:** Alviere Web (JS) SDK * **Version:** v0.1.0 ##### Getting started flow * **Step 1** - Create an authenticated web session on a secure backchannel. * **Step 2** - Include our SDK in your Web App using the session id above. * **Step 3** - Instantiate our SDK and create the required Service. * **Step 4** - Use our Service, either binding or api based (details below). ### Backend Authentication Before integrating with our SDK, you need to securely generate a session. The flow is as follows: 1. Your backend needs to generate a web session with Alviere. 2. Then, your frontend needs to include the Alviere web SDK (via script) using the previously generated session id. 3. Finally, the Alviere web sdk is ready to be instantiated and used. More details [here](#instantiate-sdk-service) Please see details on our api documentation, on the endpoint "request a web session" ### Include Web SDK ##### Include the SDK The first step is to include our SDK, ideally at the very bottom of your web app. ```plaintext (...) <script src="https://api.snd.alviere.com/sdk/js?session_id={{YOUR-SESSION-ID}}"></script> <‍/body> <‍/html> ``` Please Note: * You must include the session id obtained in the [Backend Authentication](#backend-authentication) step above. * Make sure you use the appropriate URL depending on the mode you are in; production or sandbox. ### Instantiate SDK Service ##### Instantiate SDK Service After you include our SDK, it exposes a public global variable `Alviere` where you can access our Controller Factory. You can then use this factory to instantiate the desired Alviere Service. Each controller corresponds to one Alviere Service. For instance, if you wanted to instantiate our Payments Service or our Fraud Service, you would call the below example. ```plaintext let service = Alviere.Factory.NewPaymentsController({}); ``` ```plaintext let service = Alviere.Factory.NewFraudController(); ``` ### Payments Service ##### Introduction When a payment method is added to our system through our payments service, we perform multiple tests before encrypting and storing the card details with the highest PCI standards. ##### Create Card Flow * **Create Payments Controller** - Using our factory and passing the configuration object * **Bind the SDK with your Form** - This allows us to take over the form submit * **Wait for callbacks** - We will trigger the provided callbacks whenever success/failure happens ##### Configuration Object ```plaintext { success_cb: (result: AddCardResult) => void; error_cb: (error: AddCardGatewayError) => void; validation_cb: (errors: Array<AddCardValidationError>) => void; debug: {boolean}; } ``` `success_cb` (required)\ Add Card submit success. This is a function that will receive a `AddCardResult` object `error_cb` (required)\ Add Card submit error. This is a function that will receive a `AddCardGatewayError` object `validation_cb` (required)\ Add Card form validation fail. This is a function that will receive an array of `AddCardValidationError` objects `debug`\ This, when true, will make our SDK output debug messages to console ##### AddCardResult Object The result object yields information about the payment add card process result. ```json { "card": { "payment_method_uuid": "09f46e1f-aa02-46ec-ae6d-34946f385e3d", "external_id": "string", "account_uuid": "string", "brand": "VISA", "type": "CREDIT", "country": "USA", "last_4": "0000", "status": "ACTIVE", "status_reason": "string", "flags": { "load_supported": true, "withdraw_supported": false }, "metadata": {}, "created_at": "string", "updated_at": "string" }, "validation": { "error_code": "", "error_description": "", "cvv_result": "M", "avs_result": "A" } } ``` `card.payment_method_uuid`\ This is Alviere internal card ID. This is the uuid you should store on your backend and it allows you to perform PCI compliant operations on that payment card through your backend. `card.status`\ The status of the card Allowed values: CREATED, ACTIVE, FAILED, EXPIRED, REJECTED, DELETED `card.status_reason`\ In case the card failed, this will hold the exact error reason. ##### AddCardGatewayError Object The gateway error object yields information about request failure on the network level. ```json { message: string, http_code: number, error_code: boolean, error_description: string, } ``` `message`\ An SDK error message. `http_code`\ The underlying request HTTP Status Code `error_code`\ The Alviere internal API specific error code (when applicable) ##### AddCardValidationError Object The Add Card Validation object yields information about the initial form validation result. ```json { message: string, field_id: string, field_name: string, } ``` `message`\ An SDK validation error message. `field_id`\ The DOM `id` where the validation error was triggered. `field_name`\ The DOM `name` value where the validation error was triggered. ##### Binding the Form The Payments Controller allows you to bind to any given DOM form. For that, you need to pass the DOM id to the controller. **Please note** that the form inputs must follow a specific contract with data attributes. ```javascript let payments = Alviere.Factory.NewPaymentsController({}); payments.bind("add-card-form").addCard(); ``` `data-alviere-id="chn"` For the card holder name field. `data-alviere-id="pan"`\ For the card number field (numeric - we will strip any dashes or spaces). `data-alviere-id="exp"`\ For the card expiry date (string - must be in format MM/YY). `data-alviere-id="sec"`\ For the card security code (numeric - must be 3 or 4 digits e.g. cvv). `data-alviere-id="mid"`\ This can/should be hidden field as it must have YOUR own payment method ID. This field will be stored on our servers and used for searching as well as an idempotency checking mechanism. ##### Full Example The Payments Controller allows you to bind to any given DOM form. For that you need to pass the DOM id to the controller. **Please note** the form inputs must follow a specific contract with data attributes. ```plaintext <!doctype html> <html class="no-js" lang=""> <head> <script src="https://api.snd.alviere.com/sdk/js?session_id={{YOUR-SESSION-ID}}"></script> <script> payments = Alviere.Factory.NewPaymentsController({ "success_cb": function handler(result) { console.log("received from success cb: " + result.card.payment_method_uuid) }, "error_cb": function handler(error) { console.log("received from error cb: " + error.error_description) }, "validation_cb": function handler(errors) { console.log("received from validation cb: " + errors) }, "debug": true, }); payments.bind("add-card-form").addCard(); </script> </head> <body> <form id="add-card-form"> <input id="name" type="text" data-alviere-id="chn" value="John Doe"><br> <input id="pan" type="text" data-alviere-id="pan" value="5280705922407691"><br> <input id="expiry" type="text" data-alviere-id="exp" value="11/22"><br> <input id="sec-code" type="text" data-alviere-id="sec" value="123"><br> <input type="hidden" data-alviere-id="mid" value="123456789abc"> <input type="submit"> </form> </body> </html> ``` ### Fraud Service ##### Introduction When a consumer is created, the Fraud Service will ensure that the device data is collected and sent to our Fraud Provider, in order to reduce the fraud risk. ##### Fraud Flow * **Create Fraud Controller** - Using our factory * **Start the Fraud Service** - This allows us to instantiate the fraud service ##### Full Example ```plaintext <!doctype html> <html class="no-js" lang=""> <head> <script src="https://api.snd.alviere.com/sdk/js?session_id={{YOUR-SESSION-ID}}"></script> <script> fraud = Alviere.Factory.NewFraudController(); fraud.bind().start(); </script> </head> <body> ... </body> </html> ``` ### Card Issued Service ##### Introduction With this controller you can trigger multiple operation on the Card Issuance module. ##### Set Pin Flow * **Create Card Issuance Controller** - Using our factory and passing the configuration object * **Bind the SDK with your Form** - This allows us take over the form submit event * **Wait for callbacks** - We will trigger the provided callbacks whenever success/failure happens ##### Configuration Object ```javascript { success_cb: (result: SetPinResult) => void; error_cb: (error: CardIssuanceGatewayError) => void; validation_cb: (errors: Array<CardIssuanceValidationError>) => void; debug: {boolean}; } ``` `success_cb`(required)\ Set PIN submit success. This is a function that will receive a `SetPinResult` object. `error_cb` (required)\ Set PIN submit error. This is a function that will receive a `CardIssuanceGatewayError` object. `validation_cb` (required)\ Set PIN form validation fail. This is a function that will receive an array of `CardIssuanceValidationError` objects. `debug`\ This, when true, will make our SDK output debug messages to console. ##### SetPinResult Object The result object yields information about the Set PIN request result. ```javascript { accepted: boolean, error_code: string, error_description: string, } ``` `accepted` If the request succeed or not. `error_code`\ In case the request failed, this will hold the exact error reason code. ##### CardIssuanceGatewayError Object The gateway error object yields information about request failure on the network level. ```javascript { message: string, http_code: number, error_code: boolean, error_description: string, } ``` `message`\ An SDK error message. `http_code`\ The underlying request HTTP Status Code `error_code`\ The Alviere internal API specific error code (when applicable) ##### CardIssuanceValidationError Object The Card Issuance Validation object yields information about the initial form validation result. ```javascript { message: string, field_id: string, field_name: string, } ``` `message`\ An SDK validation error message. `field_id`\ The DOM `id` where the validation error was triggered. `field_name`\ The DOM `name` value where the validation error was triggered. ##### Binding the Form The Set PIN Controller allows you to bind to any given DOM form. For that, you need to pass the DOM id to the controller. **Please note** that the form inputs must follow a specific contract with data attributes. ```javascript let card_issuance = Alviere.Factory.NewCardIssuanceController({}); card_issuance.bind("card-set-pin-form").setPin(); ``` `data-alviere-id="pin"`\ For the card PIN field. `data-alviere-id="pinc"`\ For the card PIN confirmation field. `data-alviere-id="cuid"`\ For the card UUID. ##### Full Example The Set PIN Controller allows you to bind to any given DOM form. For that, you need to pass the DOM id to the controller. **Please note** that the form inputs must follow a specific contract with data attributes. ```plaintext <!doctype html> <html class="no-js" lang=""> <head> <script src="https://api.snd.alviere.com/sdk/js?session_id={{YOUR-SESSION-ID}}"></script> <script> cardIssuance = Alviere.Factory.NewCardIssuanceController({ "success_cb": function handler(result) { console.log("received from success cb: " + result.accepted) }, "error_cb": function handler(error) { console.log("received from error cb: " + error.error_description) }, "validation_cb": function handler(errors) { console.log("received from validation cb: " + errors) }, "debug": true, }); card_issuance.bind("card-set-pin-form").setPin(); </script> </head> <body> <form id="card-set-pin-form"> <input id="pin" type="text" data-alviere-id="pin" value="1234"><br> <input id="pin-confirmation" type="text" data-alviere-id="pinc" value="1234"><br> <input type="hidden" data-alviere-id="cuid" value="650ad655-5f91-4956-866d-764072986955"> <input type="submit"> </form> </body> </html> ``` # Release Notes Stay current with what’s new, changed, and fixed in the Alviere platform. --- ## Latest Release v2524H.c — 25 November 2025 Highlights: New ACH payments endpoint --- ## Previous Releases | Version | Date | Key Updates | | -------- | ---------------- | ------------------------------------------------------------------------------------------------- | | v2524H.a | 17 November 2025 | Added HMACs for webhook verification, Account entity changes for better onboarding data modelling | # v2524H.c In this latest Alviere HIVE release, client partners can now initiate bank-to-wallet transactions via ACH. This ensures simple and automatic payment transaction processing and classification. ## **New ACH debit API for bank payment** * New `/v3/ach/debit` API created\ Partners can now initiate bank-to-wallet payments using an ACH payment method. When the payment method belongs to the external account (not the business), the system classifies it as a **PAYMENT** transaction automatically. # v2524H.a In this latest Alviere HIVE release, we’ve added more security by ensuring webhook data is trusted, untampered, and verified by Alviere. Clients can verify webhook authenticity using a secure HMAC-SHA256 signature included in every event. Also in this release, businesses or consumers can be made children of a business parent account. This improves how clients model internal or partner hierarchies, supporting more, and richer, use cases for pay-by-bank, as well as future B2B onboarding flows. ### **HMAC Signature Validation for Webhooks** Going forward, clients can verify webhook _authenticity_ using a secure HMAC-SHA256 signature included in every event. This ensures webhook data is trusted, untampered, and verifiably sent by Alviere. * New header: `X-Alviere-Signature` → HMAC-SHA256 hash of the payload. * Optional feature: existing webhooks continue to function without change. * Clients who wish to enable verification can _opt in_ by sharing their webhook secret with Alviere. ### **Allow Businesses/Consumers to be Child of Business Accounts** Users can now associate business or consumer accounts as children of a business parent account, allowing more precise hierarchy modeling and expanding support for advanced pay-by-bank and upcoming B2B onboarding flows. * Businesses or consumers can now be created as children of a business account. * Validation ensures only business accounts can act as parents. * Ownership hierarchy is visible across account data and events. * No changes required for existing clients.