# API Domain URL

---

## Sandbox 

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

## Production

* https://mapi.yuansfer.com

# Payee Registration

---

* {Domain}/v3/payee/register
* Method: `POST`

### Request 

|Field|M/C/O|Comment|
|---|---|---|
|merchantNo|Mandatory||
|storeNo|Mandatory||
|verifySign|Mandatory|signature|
|profileType|Mandatory|INDIVIDUAL, BUSINESS|
|dateOfBirth|Mandatory|payee's date of birth|
|timestamp|Mandatory|current timestamp in UTC timezone|

```json
{
    "city": "hometown",
    "country": "USA",
    "countryCode": "US",
    "customerCode": "1665425422",
    "dateOfBirth": "1999-01-01",
    "email": "JohnDoe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "merchantNo": "202333",
    "phone": "1234567890",
    "profileType": "INDIVIDUAL",
    "state": "NY",
    "storeNo": "301854",
    "street": "123 main St",
    "street2": "",
    "timestamp": "2023-02-13T10:50:58Z",
    "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": "JohnDoe@example.com"
    }
}
```

# Rerieve Payee info

---

* {Domain}/v3/payee/retrieve
* Method: `POST`

### Request

```json
{
    "customerNo": "2000305228303182610217",
    "merchantNo": "202333",
    "storeNo": "301854",
    "timestamp":"2023-02-13T12:35:14Z",
    "verifySign": "d81e8e6f33ecdbff1985dbf0210572ce"
}
```

### Response

```json
{
    "ret_msg": "query success",
    "ret_code": "000100",
    "customer": {
        "zip": "10005",
        "lastName": "Doe",
        "country": "USA",
        "updatedTime": "2023-02-13T11:46:37Z",
        "payeeStatus": "Activated",
        "city": "hometown",
        "customerCode": "1665425123",
        "dateOfBirth": "1999-01-01",
        "firstName": "John",
        "profileType": "INDIVIDUAL",
        "phone": "1234567890",
        "countryCode": "US",
        "street": "123 main St",
        "createdTime": "2023-02-13T11:45:37Z",
        "state": "NY",
        "lang": "en",
        "customerNo": "2000305228303182610217",
        "email": "JohnDoe@example.com"
    }
}
```

# Update payee info

---

* {Domain}/v3/payee/update
* Method: `POST`

### Request

```json
{
    "city": "hometown",
    "country": "USA",
    "countryCode": "US",
    "dateOfBirth": "1999-01-01",
    "firstName": "John",
    "lastName": "Doe",
    "merchantNo": "202333",
    "phone": "123456789",
    "profileType": "INDIVIDUAL",
    "state": "NY",
    "storeNo": "301854",
    "street": "123 main St",
    "street2": "",
    "timestamp": "2023-02-13T12:37:58Z",
    "customerNo": "2000305228303182610217",
    "verifySign": "cb74eb92eebadc97445d559bc5501012",
    "zip": "10006"
}
```

### Response

```json
{
    "ret_msg": "update success",
    "ret_code": "000100"
}
```


# Add payee funding source account

---

* `/v3/payee/account/create/bank-account`
* Method: `POST`

### Request

|value|comments|
|---|---|
|branchId|The 9 digit routing number.|
|bankAccountId|The  bank account number.|
|bankAccountPurpose|CHECKING, SAVINGS|
|clientIp|The creator's IP address|

```json
{
    "accountCountry": "US",
    "accountCurrency": "USD",
    "accountTag": "1a52692711",
    "accountType": "BANK_ACCOUNT",
    "bankAccountId": "7861053298",
    "branchId": "101089292",
    "bankAccountPurpose":"CHECKING",
    "customerNo": "2000305228303182610217",
    "ipnUrl": "https://example.com/webhooks",
    "merchantNo": "202333",
    "storeNo": "301854",
    "timestamp": "2023-02-13T11:50:58Z",
    "clientIp":"127.0.0.1",
    "verifySign": "23f56c32ddcd8732eced87f139d086d9"
}
```


### Response

```json
{
    "result": {
        "accountTag": "1a52692711",
        "accountStatus": "ACTIVATED",
        "country": "US",
        "firstName": "John",
        "lastName": "Doe",
        "accountType": "BANK_ACCOUNT",
        "currency": "USD",
        "accountToken": "2010305228303182765718",
        "customerNo": "2000305228292319592008",
        "email": "JohnDoe@example.com",
        "timestamp": "2023-02-13T11:48:12Z"
    },
    "ret_msg": "success",
    "ret_code": "000100"
}
```


# Retrieve payee funding source accounts(created above)

---

* {Domain}/v3/payee/payout-accounts
* Method: `POST`

### Request

```json
{
    "merchantNo": "202333",
    "storeNo": "301854",
    "customerNo": "2000305228292319592008",
    "verifySign": "4b57c4ab6f2f71e7fd7cc6046fa5e78c",
    "timestamp": "2023-02-13T11:53:58Z"
}
```

### Response

```json
{
    "accounts": [
        {
            "accountTag": "1a52692711",
            "country": "US",
            "createdAt": "2023-02-13T11:48:13Z",
            "accountType": "BANK_ACCOUNT",
            "currency": "USD",
            "accountToken": "2010305228303182765718",
            "cardNumber": "****3298",
            "status": "activated"
        }
    ],
    "ret_msg": "success",
    "user": {
        "firstName": "John",
        "lastName": "Doe",
        "customerCode": "1665425123",
        "customerNo": "2000305228292319592008",
        "email": "JohnDoe@example.com"
    },
    "ret_code": "000100"
}
```


# Transfer

---

* {Domain}/v3/payouts/pay
* Method: `POST`

### Request

```json
{
    "accountToken": "2010305228303182765718",
    "amount": "500",
    "currency": "USD",
    "customerNo": "2000305228292319592008",
    "description": "thank you",
    "invoiceId": "9aae4c685d824c5da746f97620c59eb5",
    "ipnUrl": "https://example.com/webhooks",
    "merchantNo": "202333",
    "note": "Payouts, Thanks",
    "storeNo": "301854",
    "subject": "Payouts",
    "timestamp": "2023-02-13T11:58:58Z",
    "verifySign": "8b11e8f0d7f2a412f020f266110b57ba"
}
```

### Response

***transaction status enums***

|value|comments|
|---|---|
|pending|Your payout request was received and will be processed|
|success|Funds have been credited to the recipient’s account|
|failed|This payout request has failed, so funds were not deducted from the sender’s account|
|returned|This payout request was cancelled|

```json
{
    "result": {
        "amount": "500.00",
        "transactionNo": "305588797074336092",
        "createdTime": "2023-02-13T11:58:59Z",
        "invoiceId": "9aae4c685d824c5da746f97620c59eb5",
        "currency": "USD",
        "accountToken": "2010305228303182765718",
        "customerNo": "2000305228303182610217",
        "status": "pending"
    },
    "ret_msg": "succeeded",
    "ret_code": "000100"
}
```



# Appendix

### Response Codes

|Code|Detail|
|---|---|
|000000|System Error|
|000020|Parameter Null Error|
|000021|Parameter No Related Information|
|000022|Parameters Do Not Match|
|000023|Parameter Value Error|
|000030|No Rights / Access Denied|
|000040|Account balance is not sufficient|
|000080|Supplier System's Error|
|000100|Success|