# Apply API

This API is used to apply Exchange Payment request, create corresponding transaction object in LianLian's system and send SMS verification code.

## Request

### Endpoint

```markup
https://fe-pay.lianlianpay.com/exchange/v1/bankcardpayapply
```

> Direct APIs have an additional requirement which involves our payment risk team and due diligence team. You need to contact your business development to obtain the access.

### Request Parameters

| Name             | Required | Type        | Description                                                                                                                                                                                                               |
| ---------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api\_version     | Required | String(6)   | Fixed value, `1.0`                                                                                                                                                                                                        |
| sign\_type       | Required | String(3)   | RSA                                                                                                                                                                                                                       |
| sign             | Required | String      | Signature value, refer to [signature document](../development/signature)                                                                                                                                                  |
| time\_stamp      | Required | String(14)  | The time when request is initialized. Format: yyyyMMddHHmmss, E.g. 20170801225714. The deviation can NOT exceed 30 minutes between your server and LianLian's server(GMT +8).                                             |
| oid\_partner     | Required | String(18)  | The unique identification assigned to the merchant. E.g. 201304121000001004                                                                                                                                               |
| user\_id         | Required | String(32)  | The unique identification assigned to the user in the merchant’s system                                                                                                                                                   |
| platform         | Optional | String(32)  | `platform` is used for sharing user info between multiple `oid_partner`, this requires additional settings from LianLian side                                                                                             |
| busi\_partner    | Required | String(6)   | Fixed value. Virtual products, `101001`; Physical products, `109001`                                                                                                                                                      |
| no\_order        | Required | String(32)  | Merchant transaction No.                                                                                                                                                                                                  |
| dt\_order        | Required | String(14)  | The date when the transaction is initialized. Format: yyyyMMddHHmmss, E.g. 20170801225714                                                                                                                                 |
| name\_goods      | Required | String(40)  | Product name. E.g. Pen                                                                                                                                                                                                    |
| info\_order      | Optional | String(255) | `info_order` will be sent back in synchronous or asynchronous notification for parameters transmission                                                                                                                    |
| notify\_url      | Required | String(128) | Online url where asynchronous notification should be sent, E.g. [http://www.lianlianpay.com/help/notify](http://www.lianlianpay.com/help/notify)                                                                          |
| valid\_order     | Optional | Int         | The valid period of `no_order`, in minute. The status of corresponding transaction will be set to "Closed" once its `valid_order` run out. Default: 10080 (7 days).                                                       |
| risk\_item       | Required | String      | This parameter is used for payment risk control, all required parameters should be included in the value of `risk_item` in json format, refer to [Payment Risk](../development/payment-risk-item)                         |
| pay\_type        | Required | String      | <p>M, Easy payment - Debit card <br> N, Easy payment - Credit card <br> D, Authenticate Payment</p>                                                                                                                       |
| currency\_order  | Required | String(3)   | The currency used in the transaction. Refer to [supported currencies](../development/supported-currencies)                                                                                                                |
| money\_order     | Required | String(12)  | Merchant order amount, range: 0.01 \~ 100,000,000.00, 2 decimal places are expected, in the currency of `currency_order`                                                                                                  |
| currency\_settle | Required | String(3)   | The settle currency of transaction. Currently `currency_settle` must be same with `currency_order`                                                                                                                        |
| vali\_date       | Optional | String      | The expire date of credit card. Required for credit card                                                                                                                                                                  |
| cvv2             | Optional | String      | The CVV/CVC2 of credit card. Required for credit card                                                                                                                                                                     |
| id\_type         | Optional | String(1)   | <p>0, ID card <br> 2, Passport <br> 3, Military Officer Certificate <br> 4, Hong Kong-Macau laissez-passer <br> 6, Mainland travel permit for Taiwan residents <br> 9, Police Officer card <br> X, other certificates</p> |
| id\_no           | Optional | String      | The number of User's ID card. The length need to be either 15 or 18                                                                                                                                                       |
| acct\_name       | Required | String      | The name of payer, in Chinese                                                                                                                                                                                             |
| card\_no         | Required | String      | User's card number                                                                                                                                                                                                        |
| bind\_mob        | Required | String      | User's phone number, currently only support China domestic number.                                                                                                                                                        |
| no\_agree        | Optional | String(32)  | A token which represents the key payment information, refer to [Card bind document](../relevant-api/card-bind-overview) for more details                                                                                  |

> `id_no`, `acct_name`, `id_type`, `card_no` are ignored if `no_agree` is present.

### Sample Request

```
curl https://fe-pay.lianlianpay.com/exchange/v1/bankcardpayapply \
-H "Content-type:application/json;charset=utf-8" \
-d '{
        "oid_partner": "201103171000000000",
        "dt_order": "20130515094013",
        "time_stamp": "20130515094013"
        "no_order": "2013051500001",
        "busi_partner": "101001",
        "name_goods": "羽毛球",
        "info_order": "用户13958069593购买羽毛球3桶",
        "money_order": "31.68",
        "currency_order": "USD",
        "currency_settle": "USD",
        "notify_url": "http://payhttp.xiaofubao.com/***/back.shtml",
        "valid_order": "30",
        "pay_type": "D",
        "card_no": "8888888888888888",
        "bank_code": "01020000",
        "acct_name": "张三",
        "bind_mob": "13112345678",
        "vali_date": "1402",
        "cvv2": "627",
        "id_type": "0",
        "id_no": "330401198001014616",
        "sign_type ": "RSA",
        "sign": "ZPZULntRpJwFmGNIVKwjLEF2Tze7bqs60rxQ22CqT5J1UlvGo575QK9z/+p+7E9cOoRoWzqR6xHZ6WVv3dloyGKDR0btvrdqPgUAoeaX/YOWzTh00vwcQ+HBtXE+vPTfAqjCTxiiSJEOY7ATCF1q7iP3sfQxhS0nDUug1LP3OLk="
    }'
```

## Response

The response of this API is possible to include the payment result directly when your account has **No SMS Verification Flow** setup, for more details, please contact our technical support.

### Parameters

| Name      | Required | Type        | Description                                                                                                           |
| --------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| ret\_code | Required | String(4)   | Return code, whether the request is handled successfully or not. Refer to [return codes](../development/return-codes) |
| ret\_msg  | Required | String(100) | Return message, description of `ret_code`, in Chinese                                                                 |

The following parameters are returned only when `ret_code=0000`:

| Name            | Required | Type       | Description                                                                                                                                                                      |
| --------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| oid\_partner    | Required | String(18) | The unique identification assigned to the merchant. E.g. 201304121000001004                                                                                                      |
| sign\_type      | Required | String(3)  | Fixed value, RSA                                                                                                                                                                 |
| sign            | Required | String     | Signature value, refer to [signature document](../development/signature)                                                                                                         |
| no\_order       | Required | String(32) | Merchant transaction No.                                                                                                                                                         |
| dt\_order       | Required | String(14) | The date when the transaction is initialized. Format: yyyyMMddHHmmss, E.g. 20170801225714                                                                                        |
| oid\_paybill    | Optional | String(18) | Unique transaction No. in LianLian system. E.g. 2011030900001098. Returned when the transaction object is created successfully.                                                  |
| currency\_order | Required | String(3)  | The currency used in the transaction. Refer to [supported currencies](../development/supported-currencies)                                                                       |
| money\_order    | Required | String(12) | Merchant transaction amount, range: 0.01 \~ 100,000,000.00, 2 decimal places are expected                                                                                        |
| result\_pay     | Optional | String     | <p>Payment result. <br> SUCCESS - Payment proceed successfully <br> PROCESSING -  Payment is processing. Return only when <strong>No SMS Verification Flow</strong> is setup</p> |
| token           | Optional | String     | Won't return if **No SMS Verification Flow** is setup.  Used for [Exchange Payment Verify API](exchange-payment-verify-api)                                                      |

The following parameters are returned only when `result_pay=SUCCESS`:

| Name             | Required | Type        | Description                                                                                                                              |
| ---------------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| settle\_date     | Required | String(8)   | Format YYYYMMDD.                                                                                                                         |
| info\_order      | Optional | String(255) | Returns when `info_order` is sent in API requests                                                                                        |
| pay\_type        | Required | String(1)   | The pay type used in current transaction.                                                                                                |
| currency\_settle | Required | String(3)   | The settle currency of transaction                                                                                                       |
| money\_settle    | Required | String(12)  | The settle amount of transaction                                                                                                         |
| currency\_pay    | Required | String(3)   | The currency of which the payer used. Refer to [supported currencies](../development/supported-currencies)                               |
| money\_pay       | Required | String(12)  | The amount of which the payer payed                                                                                                      |
| exchange\_rate   | Required | String      | The exchange rate of current transaction                                                                                                 |
| no\_agree        | Optional | String(16)  | A token which represents the key payment information, refer to [Card bind document](../relevant-api/card-bind-overview) for more details |

### Sample Response

Below is a sample response without **No SMS Verification Flow** when `ret_code=0000`.

```javascript
{
    "ret_code": "0000",
    "ret_msg": "交易成功",
    "token": "D096DBA0E3E0CC8F1D504C06E71D292D",
    "oid_partner": "201103171000000000",
    "dt_order": "20130515094013",
    "no_order": "2013051500001",
    "oid_paybill": "2013051613121201",
    "money_order": "31.68",
    "currency_order": "USD",
    "sign_type": "RSA",
    "sign": "ZPZULntRpJwFmGNIVKwjLEF2Tze7bqs60rxQ22CqT5J1UlvGo575QK9z/+p+7E9cOoRoWzqR6xHZ6WVv3dloyGKDR0btvrdqPgUAoeaX/YOWzTh00vwcQ+HBtXE+vPTfAqjCTxiiSJEOY7ATCF1q7iP3sfQxhS0nDUug1LP3OLk="
}
```
