ALVIERE Card Issuance API

This section describes how to issue and manage cards with the Alviere platform. To issue cards, you'll need to have a Cardholder Program with Alviere. ### Card Types The Alviere platform supports the following types of cards: | Type | Description | |------|-------------| | **DEBIT** | This is a type of card that uses the balance of the user account wallet in order to authorize transactions. | | **PREPAID** | This is a type of card that needs to be preloaded with a balance in order to authorize transactions. | | **GIFT CARD** | This is a type of card that has a fixed balance preset at the moment of the issuance of the card. | The main difference between a Debit or Prepaid card and a Gift Card is the latter does not require KYC to be performed. ### Card Products In the Alviere platform, each card on a program is identified by a unique `product_id` that will be provided to your company at the moment of the program setup. A `product_id` is always associated to only one of the card types mentioned above. Your program can support any number of card configurations and Alviere will assign individual `product_id` for each one of the cards. Product IDs also define if the card is issued virtually or physically, the design/card art of the card, carrier design (physical cards only), and all the settings, limitations, and fees of the card. These settings will be defined at the moment of the setup of your Cardholder Program, and cannot be set using the API. ### Shipping Address Rules The shipping address defines where a card is shipped to via postal service. This setting does not apply to virtual card products. - Virtual card product types will not have this field present. - This field is mandatory for Gift Card product types. - For non-Gift Card programs, if this property is present, the card will be shipped to this address instead of the address found on the user account ### Card Statuses The following table details the issued card statuses in the Alviere platform: | Type | Description | |------|-------------| | **CREATED** | The card was created in the Alviere platform; this is the initial status for all card issuance requests. | | **PENDING** | The card is currently pending; this could happen due to a secondary ID verification. | | **PROCESSING** | The card is currently processing. | | **ACTIVE** | The card is active and ready to be used. | | **FROZEN** | The card is currently frozen and all transaction authorizations will be declined. | | **SET_TO_EMBOSS** | The card is set to be embossed by the manufacturing partner; this status is only applicable to physical card products. | | **SHIPPED** | The card has been shipped via mail; this status is only applicable to physical card products. | | **READY_TO_ACTIVATE** | The card is ready to be activated and for the PIN to be set; this status is only applicable to physical card products. | | **RETURNED_MAIL** | The card was returned via the postal service; this status is only applicable to physical card products. | | **LOST_STOLEN** | The card has been reported by the cardholder as stolen or lost; 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 expired; this is a final status. | ### Incentives Alviere supports incentivization/bonuses for all of its cards. Two types of incentives are supported: | Type | Description | |------|-------------| | **CASHBACK** | The cardholder will receive into the balance of their account, a cashback of the defined amount/percentage after a successful authorization of a card transaction. | | **BOOST** | The card authorization will succeed if the balance + boost amount/percentage are equal or lower to the amount being authorized. For example, if the card balance is $100 and there's a BOOST incentive of 10%, the system will authorize a transaction up to $110. | Incentives can be configured individually for each card issued through the API. You can configure an amount of the incentive and/or the valid merchants where the incentive is to be applied. The following rules are applied to the incentives: - **Percentage**: This property defines the percentage of the authorization amount to apply the incentive (BOOST or CASHBACK) - **Cap**: This property defines a cap for the incentive (BOOST or CASHBACK); for example, if you have a 10% cashback with a $5 cap, and the authorized transaction is $100, the value of the cashback into the cardholder's balance will be $5 You can also limit the merchants where the incentives are to be applied; i.e. "only apply this incentive on purchases for merchant X". Merchant incentives can be applied to specific merchant IDs or to merchant names. In the case of merchant names, the system will do a match of the name; i.e. it will be applied as long as the merchant name exists in the merchant description field. For example, if this property is set to "Alviere", then a transaction for "Alviere, Inc." and a transaction for "Alviere Financial Services" will both apply. ### Allowed Merchants You can also specify that the card balance can only be spent on specific merchants; i.e. the card was issued with a balance that can only be spent on specific merchant(s). In the case of merchant names, the system will do a match of the name; for example, if this property is set to "Alviere", then a transaction for "Alviere, Inc." and a transaction for "Alviere Financial Services" will both apply.