docs/payouts.md

# API Domain URL

---

## Sandbox 

* https://mapi.yuansfer.yunkeguan.com

## Production

* https://mapi.yuansfer.com

# Payee Registration

---

* {Domain}/v3/payee/register

### Request 

* `governmentIdType`: 中国大陆用户需要使用身份证号码，type = `ID_CARD`

* 注册成功之后，Payee会收到注册通知邮件，根据指引登录Yuansfer Portal提交相关信息，激活账户之后才可以接收转账。

```json
{
    "city": "hometown",
    "country": "USA",
    "countryCode": "US",
    "customerCode": "1665425422",
    "dateOfBirth": "1999-01-01",
    "email": "[email protected]",
    "firstName": "John",
    "governmentId": "123456789",
    "governmentIdType": "ID_CARD",
    "lastName": "Doe",
    "merchantNo": "202333",
    "phone": "1234567890",
    "profileType": "INDIVIDUAL",
    "state": "WA",
    "storeNo": "301854",
    "street": "123 main St",
    "street2": "",
    "verifySign": "2e2294120492ca91b0be1db9a3c98c0e",
    "zip": "10005"
}
```

### Response

```json
{
    "ret_msg": "success",
    "ret_code": "000100",
    "customer":
    {
        "firstName": "John",
        "lastName": "Doe",
        "customerCode": "1665425422",
        "createdTime": "2022-10-10T18:15:19Z",
        "customerNo": "2000305228292319592008",
        "email": "[email protected]"
    }
}
```


# 查询收款人账号信息

---

* {Domain}/v3/payee/payout-accounts

### Request

* 查询由收款人登录portal，自己添加的银行账号，PayPal账号，Alipay账号等

```json
{
    "merchantNo": "202333",
    "storeNo": "301854",
    "customerNo": "2000305228289295850180",
    "verifySign": "05a150f56706f9a435748eb986c2daad",
    "timestamp": "2022-10-10T18:25:52Z"
}
```

### Response

```json
{
    "accounts": [
        {
            "accountTag": "ee1d4197-36aa-4991-952c-0a9b35f505dd",
            "country": "CN",
            "createdAt": "2022-09-05T18:27:40Z",
            "accountType": "BANK_ACCOUNT",
            "currency": "CNY",
            "accountToken": "2010305228289296332658",
            "cardNumber": "****5655",
            "status": "activated"
        }
    ],
    "ret_msg": "success",
    "user": {
        "firstName": "俊义",
        "lastName": "卢",
        "customerNo": "2000305228289295850180",
        "email": "[email protected]"
    },
    "ret_code": "000100"
}
```


# Transfer

---

* 需要首先通过查询API获得收款账号: `accountToken`

* {Domain}/v3/payouts/pay

### Request

```json
{
    "accountToken": "2010305228264750806137",
    "amount": "500",
    "currency": "USD",
    "customerNo": "2000305228264750734154",
    "description": "thank you",
    "invoiceId": "9aae4c685d824c5da746f97620c59eb3",
    "ipnUrl": "https://example.com/notify",
    "merchantNo": "202333",
    "note": "Payouts, Thanks",
    "storeNo": "301854",
    "subject": "Payouts",
    "verifySign": "5110a71cfda71dc5d05bf67ce7b7e4b4"
}
```

### Response

```json
{
    "result":
    {
        "amount": "500.00",
        "transactionFee": "20.00",
        "transactionNo": "305464260013338582",
        "createdTime": "2022-10-10T18:33:32Z",
        "invoiceId": "9aae4c685d824c5da746f97620c59eb3",
        "currency": "USD",
        "accountToken": "2010305228264750806137",
        "customerNo": "2000305228264750734154",
        "status": "pending"
    },
    "ret_msg": "pending",
    "ret_code": "000100"
}
```

# Retrieve Payouts

---

* {Domain}/v3/payouts/inquiry

* `transactionNo` 和 `invoiceId` 二者都可以用来查询交易记录，二选一

### Request

```json
{
    "merchantNo":"202333",
    "storeNo":"301854",
    "verifySign":"41af5995afd170329ed0a268fac3e0a1",
    "invoiceId":"85cfabefaebc265c87da15a0504656b4",
    "timestamp":"2022-10-18T21:16:32Z",
    "transactionNo":"305448035595256529"
}
```

### Response

```json
{
    "result": {
        "amount": "100.00",
        "transactionFee": "12.00",
        "transactionNo": "305448035595256529",
        "createdTime": "2022-10-18T15:45:11Z",
        "invoiceId": "85cfabefaebc265c87da15a0504656b4",
        "currency": "USD",
        "accountToken": "2010305228264750806137",
        "paymentTime": "2022-10-18T15:45:11Z",
        "status": "pending"
    },
    "ret_msg": "query success",
    "ret_code": "000100"
}
```