# 交通卡充值

交通卡的充值过程分为：卡片展示、生成并支付充值订单和发起充值三个步骤，整体流程如下图，相关接口定义请参照钱包服务API。

*   开发者的app启动后，可调用getCardMetadataInDevice接口获取指定设备上开发者的app可以访问的交通卡的信息以数组的方式返回。如返回的数组为空，则表示开发者的app在该设备上没有可访问的交通卡，无需显示卡片开通入口；如返回数组不为空，则按具体的交通卡信息做展示。如果交通卡信息中包括卡号、余额信息，则表明该卡片在设备上已开通，显示卡片信息即可；否则可显示卡片的开通入口。
    
*   用户选择了给指定的交通卡充值时，开发者的app需向开发者的后台服务器发起充值订单的生成请求，并让用户完成支付。
    
*   开发者的app在查询到订单已支付完成后，可调用rechargeTransitCard接口发起将订单金额充值到卡内的处理过程。如果充值正常结束，开发者的app会收到充值成功的返回值并携带了新的余额；如果充值过程出现失败，在钱包app自行发起重试后仍然失败的情况下，钱包会发起订单退款的请求。在SP TSM或开发者的后台服务器确认订单状态是可退款的情况下，需调用对应支付渠道的订单撤销接口，将订单金额原路退回，这种情况下开发者的app会收到充值失败的错误码，可参考ArkTS API错误码。
    

#### 开发步骤

1.  获取设备上已开通的交通卡列表。
    
    初始化TransitCardClient时，构造方法的第二个入参callerId是接口调用方ID。开发者可以联系钱包运营申请交通卡服务时获取。
    
    ```
    import { common } from '@kit.AbilityKit';
    import { walletTransitCard } from '@kit.WalletKit';
    import { BusinessError } from '@kit.BasicServicesKit';
    
    @Entry
    @Component
    struct Index {
      private transitCardClient: walletTransitCard.TransitCardClient = new walletTransitCard.TransitCardClient(this.getUIContext().getHostContext() as common.UIAbilityContext, 'callerId');
    
      async getCardMetadataInDevice() {
        this.transitCardClient.getCardMetadataInDevice(walletTransitCard.DeviceType.DEVICE_PHONE).then((result) => {
          console.info(`Succeeded in getting cardMetadataInDevice`);
        }).catch((err: BusinessError) => {
          console.error(`Failed to get CardMetadataInDevice, code:${err.code}, message:${err.message}`);
        })
      }
    
      build() {
        // your application UI
      }
    }
    ```
    
2.  交通卡充值。
    
    ```
    import { common } from '@kit.AbilityKit';
    import { walletTransitCard } from '@kit.WalletKit';
    import { BusinessError } from '@kit.BasicServicesKit';
    
    @Entry
    @Component
    struct Index {
      private transitCardClient: walletTransitCard.TransitCardClient = new walletTransitCard.TransitCardClient(this.getUIContext().getHostContext() as common.UIAbilityContext, 'callerId');
    
      async rechargeTransitCard() {
        // number of the enabled traffic card returned by the getCardMetadataInDevice interface
        const logicalCardNumber = 'logicalCardNumber';
        // the specifiedDeviceId returned by the getCardMetadataInDevice interface
        const specifiedDeviceId = 'specifiedDeviceId';
        // order ID generated after payment in a developer's app, which is implemented by the developer
        const serverOrderId = 'serverOrderId';
        this.transitCardClient.rechargeTransitCard(logicalCardNumber, specifiedDeviceId, serverOrderId).then((result) => {
          console.info(`Succeeded in recharging TransitCard`);
        }).catch((err: BusinessError) => {
          console.error(`Failed to recharge TransitCard, code:${err.code}, message:${err.message}`);
        })
      }
    
      build() {
        // your application UI
      }
    }
    ```