> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 资源

> 使用 UQPAY Java SDK 调用 Banking、Issuing、Connect、Payment、Supporting 与 Simulator 资源。

本页覆盖 `UqpayClient` 上所有资源命名空间，每个命名空间对应一条 UQPAY 产品线。

## Banking

### 余额

```java theme={null}
import com.uqpay.sdk.v2.banking.model.*;

ListBalancesResponse balances = client.banking().getBalances().list(
    new ListBalancesRequest().setPageSize(20).setPageNumber(1)
);
Balance balance = client.banking().getBalances().get("SGD");

// 余额流水
ListBalanceTransactionsRequest txReq = new ListBalanceTransactionsRequest();
txReq.setPageSize(20);
txReq.setPageNumber(1);
ListBalanceTransactionsResponse txns = client.banking().getBalances().listTransactions(txReq);
```

### 转账

```java theme={null}
CreateTransferRequest transferReq = new CreateTransferRequest();
transferReq.setSourceAccountId("acc-123");
transferReq.setDestinationAccountId("acc-456");
transferReq.setCurrency("SGD");
transferReq.setAmount("100.00");
CreateTransferResponse transfer = client.banking().getTransfers().create(transferReq);

ListTransfersResponse transfers = client.banking().getTransfers().list(
    new ListTransfersRequest().setPageSize(20).setPageNumber(1)
);
Transfer retrieved = client.banking().getTransfers().get("transfer-id");
```

### 充值

```java theme={null}
ListDepositsResponse deposits = client.banking().getDeposits().list(
    new ListDepositsRequest().setPageSize(20).setPageNumber(1)
);
Deposit deposit = client.banking().getDeposits().get("deposit-id");
```

### 受益人

```java theme={null}
CreateBeneficiaryResponse beneficiary = client.banking().getBeneficiaries().create(createBeneficiaryReq);
ListBeneficiariesResponse beneficiaries = client.banking().getBeneficiaries().list(listBeneficiaryReq);
Beneficiary ben = client.banking().getBeneficiaries().get("ben-id");
```

### 出款

```java theme={null}
CreatePayoutRequest payoutReq = new CreatePayoutRequest();
payoutReq.setBeneficiaryId("ben-123");
payoutReq.setCurrency("SGD");
payoutReq.setAmount("50.00");
payoutReq.setPurposeCode("PERSONAL");
CreatePayoutResponse payout = client.banking().getPayouts().create(payoutReq);
```

### 虚拟账户

```java theme={null}
CreateVirtualAccountResponse va = client.banking().getVirtualAccounts().create(createVaReq);
ListVirtualAccountsResponse vas = client.banking().getVirtualAccounts().list(listVaReq);
```

### 换汇

```java theme={null}
CreateConversionQuoteResponse quote = client.banking().getConversions().createQuote(quoteReq);
CreateConversionResponse conversion = client.banking().getConversions().create(createConversionReq);
```

### 汇率

```java theme={null}
ListExchangeRatesResponse rates = client.banking().getExchangeRates().list(listRatesReq);
```

## Issuing

### 持卡人

SDK 支持三档 KYC——Simplified、Standard 与 Enhanced。

**Simplified KYC**——仅需基础字段：

```java theme={null}
import com.uqpay.sdk.v2.issuing.model.*;

CreateCardholderRequest request = new CreateCardholderRequest();
request.setEmail("user@example.com");
request.setFirstName("Jane");
request.setLastName("Smith");
request.setCountryCode("SG");
request.setPhoneNumber("+6512345678");
request.setDateOfBirth("1990-01-01");

CreateCardholderResponse cardholder = client.issuing().getCardholders().create(request);
```

**Standard KYC**——增加性别、国籍、身份证件和居住地址：

```java theme={null}
CreateCardholderRequest standardReq = new CreateCardholderRequest();
standardReq.setEmail("user@example.com");
standardReq.setFirstName("Bob");
standardReq.setLastName("Lee");
standardReq.setCountryCode("SG");
standardReq.setPhoneNumber("+6598765432");
standardReq.setDateOfBirth("1988-11-03");
standardReq.setGender("MALE");
standardReq.setNationality("SG");

Identity identity = new Identity();
identity.setType("PASSPORT");
identity.setNumber("E1234567");
standardReq.setIdentity(identity);

ResidentialAddress addr = new ResidentialAddress();
addr.setCountry("SG");
addr.setState("Singapore");
addr.setCity("Singapore");
addr.setLine1("1 Raffles Place");
addr.setLineEn("1 Raffles Place");
addr.setPostalCode("048616");
standardReq.setResidentialAddress(addr);

CreateCardholderResponse stdCardholder = client.issuing().getCardholders().create(standardReq);
```

**Enhanced KYC**——SUMSUB 跳转，返回 IDV 验证 URL：

```java theme={null}
KycVerification kyc = new KycVerification();
kyc.setMethod("SUMSUB_REDIRECT");
request.setKycVerification(kyc);

CreateCardholderResponse enhanced = client.issuing().getCardholders().create(request);
System.out.println("IDV URL: " + enhanced.getIdvVerificationUrl());
```

**读取 / 列表 / 更新：**

```java theme={null}
Cardholder ch = client.issuing().getCardholders().get("ch-id");
ListCardholdersResponse list = client.issuing().getCardholders().list(
    new ListCardholdersRequest().setPageSize(20).setPageNumber(1).setCardholderStatus("SUCCESS")
);

UpdateCardholderRequest updateReq = new UpdateCardholderRequest();
updateReq.setResidentialAddress(addr);
client.issuing().getCardholders().update("ch-id", updateReq);
```

### 卡片

```java theme={null}
// 创建卡片
CreateCardRequest cardReq = new CreateCardRequest();
cardReq.setCardCurrency("SGD");
cardReq.setCardholderId(cardholder.getCardholderId());
cardReq.setCardProductId("prod-123");

CardCreationResponse card = client.issuing().getCards().create(cardReq);

// 创建 ONE_TIME 卡，配置自动取消触发
CreateCardRequest oneTimeReq = new CreateCardRequest();
oneTimeReq.setCardCurrency("SGD");
oneTimeReq.setCardholderId(cardholder.getCardholderId());
oneTimeReq.setCardProductId("prod-123");
oneTimeReq.setUsageType("ONE_TIME");
oneTimeReq.setAutoCancelTrigger("ON_AUTH");

// 创建卡片并补充 KYC 字段
CardholderRequiredFields fields = new CardholderRequiredFields();
fields.setGender("FEMALE");
fields.setNationality("SG");
fields.setIdentity(identity);
fields.setResidentialAddress(addr);
cardReq.setCardholderRequiredFields(fields);

// 读取、列表
RetrieveCardResponse retrieved = client.issuing().getCards().get("card-id");
ListCardsResponse cards = client.issuing().getCards().list(
    new ListCardsRequest().setPageSize(20).setPageNumber(1)
);

// 冻结 / 解除冻结
UpdateCardStatusRequest freeze = new UpdateCardStatusRequest();
freeze.setCardStatus("FROZEN");
client.issuing().getCards().updateStatus("card-id", freeze);

// 充值与提现
CardOrderRequest rechargeReq = new CardOrderRequest();
rechargeReq.setAmount(100.00);
CardOrder recharge = client.issuing().getCards().recharge("card-id", rechargeReq);

CardOrderRequest withdrawReq = new CardOrderRequest();
withdrawReq.setAmount(50.00);
CardOrder withdraw = client.issuing().getCards().withdraw("card-id", withdrawReq);
```

### 交易、产品、余额与转账

```java theme={null}
// 交易
ListTransactionsResponse txns = client.issuing().getTransactions().list(
    new ListTransactionsRequest().setPageSize(20).setPageNumber(1).setCardId("card-id")
);
Transaction txn = client.issuing().getTransactions().get("txn-id");

// 产品
ListProductsResponse products = client.issuing().getProducts().list(
    new ListProductsRequest().setPageSize(20).setPageNumber(1)
);

// Issuing 余额
ListIssuingBalancesResponse issuingBalances = client.issuing().getBalances().list(listReq);
IssuingBalance issuingBalance = client.issuing().getBalances().get("SGD");

// Issuing 转账
CreateIssuingTransferResponse issuingTransfer = client.issuing().getTransfers().create(createIssuingTransferReq);
```

## Connect

```java theme={null}
import com.uqpay.sdk.v2.connect.model.*;

ListAccountsResponse accounts = client.connect().getAccounts().list(
    new ListAccountsRequest().setPageSize(20).setPageNumber(1)
);
Account account = client.connect().getAccounts().get("acc-id");
Account accountByBizCode = client.connect().getAccounts().get("acc-id", "BUSINESS_CODE");
```

## Payment

### Payment intent

```java theme={null}
import com.uqpay.sdk.v2.payment.model.*;

CreatePaymentIntentRequest intentReq = new CreatePaymentIntentRequest();
intentReq.setAmount("100.00");
intentReq.setCurrency("SGD");
CreatePaymentIntentResponse intent = client.payment().getPaymentIntents().create(intentReq);

client.payment().getPaymentIntents().confirm(intent.getPaymentIntentId(), confirmReq);
client.payment().getPaymentIntents().capture(intent.getPaymentIntentId(), captureReq);
client.payment().getPaymentIntents().cancel(intent.getPaymentIntentId());

ListPaymentIntentsResponse intents = client.payment().getPaymentIntents().list(listIntentsReq);
```

### 退款

```java theme={null}
CreateRefundRequest refundReq = new CreateRefundRequest();
refundReq.setPaymentIntentId(intent.getPaymentIntentId());
refundReq.setAmount("50.00");
CreateRefundResponse refund = client.payment().getRefunds().create(refundReq);
```

### 银行账户

```java theme={null}
CreateBankAccountResponse bankAccount = client.payment().getBankAccounts().create(bankAccountReq);
```

### 出款

```java theme={null}
CreatePayoutResponse payout = client.payment().getPayouts().create(payoutReq);
```

### 余额与 Attempt

```java theme={null}
ListPaymentBalancesResponse paymentBalances = client.payment().getBalances().list(listBalReq);
ListPaymentAttemptsResponse attempts = client.payment().getPaymentAttempts().list(listAttemptsReq);
```

## Supporting（文件上传与下载）

```java theme={null}
import com.uqpay.sdk.v2.supporting.model.*;
import java.io.File;

// 上传文件
File doc = new File("kyc-document.pdf");
UploadFileResponse uploaded = client.supporting().getFiles().upload(doc, "KYC document");
System.out.println("File ID: " + uploaded.getFileId());

// 获取下载链接
DownloadLinksRequest dlReq = new DownloadLinksRequest(List.of(uploaded.getFileId()));
DownloadLinksResponse links = client.supporting().getFiles().getDownloadLinks(dlReq);
links.getFiles().forEach(f -> System.out.println("URL: " + f.getUrl()));
```

## 模拟器（仅沙盒）

<Warning>
  模拟器仅在 `sandbox` 环境可用。在生产环境调用模拟器方法会抛出 `UqpayException`。
</Warning>

```java theme={null}
import com.uqpay.sdk.v2.simulator.model.*;

// 模拟一次卡授权
SimulateAuthorizationRequest authReq = new SimulateAuthorizationRequest();
authReq.setCardId("card-123");
authReq.setTransactionAmount(25.00);
authReq.setTransactionCurrency("SGD");
authReq.setMerchantName("Coffee Shop");
SimulateAuthorizationResponse auth = client.simulator().getIssuing().authorize(authReq);

// 模拟一次冲正
SimulateReversalRequest revReq = new SimulateReversalRequest();
revReq.setTransactionId(auth.getTransactionId());
client.simulator().getIssuing().reverse(revReq);

// 模拟一笔充值
SimulateDepositRequest depositReq = new SimulateDepositRequest();
depositReq.setCurrency("SGD");
depositReq.setAmount(500.00);
SimulateDepositResponse deposit = client.simulator().getDeposits().simulate(depositReq);
```

## API 覆盖范围

### Banking API

| 资源                   | 操作                                                     |
| -------------------- | ------------------------------------------------------ |
| **Balances**         | Get、List、ListTransactions                              |
| **Transfers**        | Create、List、Get                                        |
| **Deposits**         | List、Get                                               |
| **Beneficiaries**    | Create、List、Get、Update、Delete、ListPaymentMethods、Check |
| **Payouts**          | Create、List、Get                                        |
| **Virtual Accounts** | Create、List                                            |
| **Conversions**      | CreateQuote、Create、List、Get、ListConversionDates        |
| **Exchange Rates**   | List                                                   |

### Issuing API

| 资源                | 操作                                                           |
| ----------------- | ------------------------------------------------------------ |
| **Cardholders**   | Create（Simplified / Standard / Enhanced KYC）、Get、List、Update |
| **Cards**         | Create、Get、GetSecure、List、Recharge、Withdraw、UpdateStatus     |
| **Transactions**  | Get、List                                                     |
| **Products**      | List                                                         |
| **Balances**      | Get、List、ListTransactions                                    |
| **Transfers**     | Create、List、Get                                              |
| **Reports**       | Create、Get                                                   |
| **Auth Decision** | 基于 PGP 的实时授权                                                 |

### Connect API

| 资源           | 操作       |
| ------------ | -------- |
| **Accounts** | Get、List |

### Payment API

| 资源                   | 操作                                     |
| -------------------- | -------------------------------------- |
| **Payment Intents**  | Create、Confirm、Capture、Cancel、List、Get |
| **Refunds**          | Create、List、Get                        |
| **Bank Accounts**    | Create、List、Get                        |
| **Payouts**          | Create、List、Get                        |
| **Balances**         | List                                   |
| **Payment Attempts** | List、Get                               |
| **Settlements**      | List                                   |

### Supporting API

| 资源        | 操作                      |
| --------- | ----------------------- |
| **Files** | Upload、GetDownloadLinks |

### 模拟器（仅沙盒）

| 资源           | 操作                |
| ------------ | ----------------- |
| **Issuing**  | Authorize、Reverse |
| **Deposits** | Simulate          |