# createPaymentSession (EasySafePay)

> This API is used to generate a payment session for integrating client-side SDK. The API response provides encrypted session data, which can be used to initiate the client-side SDK. This SDK streamlines the payment process and frees you from manually calling multiple APIs.

`POST /v1/payments/createPaymentSession`

This API is used to generate a payment session for integrating client-side SDK. The API response provides encrypted session data, which can be used to initiate the client-side SDK. This SDK streamlines the payment process and frees you from manually calling multiple APIs.   

# Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see： 

-   [Request header](https://docs.antom.com/ac/ams/api_fund.md#ML5ur)
-   [Response header](https://docs.antom.com/ac/ams/api_fund.md#WWH90)

> **Note**: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
>
> -   If the data type of a field is Integer and its value is `20`, set it as "`20`". 
> -   If the data type of a field is Boolean and its value is `true`, set it as "`true`".

## Request parameters

#### env (Env)

Information about the environment where the order is placed.

##### clientIp (String)

The IP address of the client device.

> Note: Specify this parameter when you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

More information:

- Maximum length: 64 characters

#### order (Order, REQUIRED)

The order information, such as buyer, merchant, goods, amount, shipping information, and purchase environment. This field is used for different purposes:

-   During the payment process, this field is mainly used by Antom for risk control or anti-money laundering. 
-   After the payment is completed, this field is used for recording and reporting purposes such as purchase tracking and regulatory reporting.

##### orderAmount (Amount, REQUIRED)

The order amount of the merchant that directly provides services or goods to the customer. This field is used for user consumption records display or payment results page.

###### currency (String, REQUIRED)

The transaction currency that is specified in the contract. A 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.

More information:

- Maximum length: 3 characters

###### value (Integer, REQUIRED)

The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a 0-decimal currency).

> Note: For details about the smallest currency unit, see [Smallest unit of the currency](https://docs.antom.com/ac/ref/cc.md#ONkIe).

More information:

- Value range: 1 - unlimited

##### referenceOrderId (String, REQUIRED)

The unique ID to identify the order on the merchant side, which is assigned by the merchant that provides services or goods directly to the customer. This field is used for user consumption records display and other further actions such as disputes track or handling of customer complaints.

More information:

- Maximum length: 64 characters

##### orderDescription (String, REQUIRED)

Summary description of the order, which is used for user consumption records display or other further actions.

More information:

- Maximum length: 256 characters

##### goods (Array<Goods>)

Goods information, including the ID, name, price, and quantity of the goods in the order.

> Note: Specify this parameter if you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

More information:

- Maximum size: 100 elements

###### referenceGoodsId (String, REQUIRED)

The unique ID to identify the goods.

More information:

- Maximum length: 64 characters

###### goodsName (String, REQUIRED)

Goods name.

More information:

- Maximum length: 256 characters

###### goodsCategory (String)

The category of the goods. If the goods have multiple layers for categorization, use slashes between different categories and write the parent category before the subcategory, such as `Digital Goods/Digital Vouchers/Food and Beverages`.

> Note: Specify this parameter if you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

More information:

- Maximum length: 64 characters

###### goodsUnitAmount (Amount)

Price of goods.

> Note: Specify this parameter if you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

###### currency (String, REQUIRED)

The 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.

More information:

- Maximum length: 3 characters

###### value (Integer, REQUIRED)

The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a 0-decimal currency).

> Note: For details about the smallest currency unit, see [Smallest unit of the currency](https://docs.antom.com/ac/ref/cc.md#ONkIe).

More information:

- Value range: 1 - unlimited

###### goodsQuantity (Integer)

Quantity of goods.

> Note: Specify this parameter if you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

More information:

- Value range: 1 - unlimited

###### goodsUrl (String)

The URL of the website where the user places an order.

> Note: Specify this parameter if you require risk control. Providing this information helps to identify black-market behavior.

More information:

- Maximum length: 2048 characters

###### deliveryMethodType (String)

The delivery method of the goods. Valid values are:

-   `PHYSICAL`: indicates that the delivery method is physical delivery.
-   `DIGITAL`: indicates that the delivery method is digital delivery.

> Note: Specify this parameter if you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

More information:

- Maximum length: 32 characters

##### shipping (Shipping)

Shipping information, including information about the recipient (name, phone number, email, and shipping address), and shipping service provider.

> Note: Specify this parameter when you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

###### shippingName (UserName)

The name of the recipient.

> Note: Specify this parameter when you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

###### firstName (String, REQUIRED)

First name.

More information:

- Maximum length: 32 characters

###### middleName (String)

Middle name

More information:

- Maximum length: 32 characters

###### lastName (String, REQUIRED)

Last name

More information:

- Maximum length: 32 characters

###### fullName (String)

Full name

More information:

- Maximum length: 128 characters

###### shippingAddress (Address)

Shipping address.

> Note: Specify this parameter if you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

###### region (String, REQUIRED)

The 2-letter country or region code. For more information, see [ISO 3166 Country Codes](https://www.iso.org/obp/ui/#search) standard.

More information:

- Maximum length: 2 characters

###### state (String)

The state, country, or province name.

More information:

- Maximum length: 8 characters

###### city (String)

The city, district, suburb, town, or village name.

More information:

- Maximum length: 32 characters

###### address1 (String)

Address line 1, for example, the street address, PO box, and company name.

More information:

- Maximum length: 256 characters

###### address2 (String)

Address line 2, for example, the apartment, suite, unit, and building information.

More information:

- Maximum length: 256 characters

###### zipCode (String)

ZIP or postal code

More information:

- Maximum length: 32 characters

###### shippingCarrier (String)

The delivery service provider for shipping a physical product, such as FedEx, UPS, or USPS.

> Note: Specify this parameter if you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

More information:

- Maximum length: 128 characters

###### shippingPhoneNo (String)

The phone number of a recipient (including extension).

> Note: Specify this parameter when you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

More information:

- Maximum length: 16 characters

###### shipToEmail (String)

The email address where virtual goods are sent.

> Specify this parameter when one of the following conditions is met:
>
> -   if you require risk control.
> -   if you are a digital and entertainment merchant.
>
> Providing this information helps to increase fraud and identity theft detection.

More information:

- Maximum length: 64 characters

##### buyer (Buyer)

Buyer information, including the ID, name, phone number, and email of the buyer.

> Note: Specify this parameter when you require risk control.
>
> Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

###### referenceBuyerId (String)

The unique ID to identify the buyer.

> Specify this parameter:
>
> -   When you require risk control.
> -   When the value of _productScene_ is `EASY_PAY`.
>
> Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

More information:

- Maximum length: 64 characters

###### buyerName (UserName)

The name of the buyer.

> Note: Specify this parameter when you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

###### firstName (String, REQUIRED)

First name.

More information:

- Maximum length: 32 characters

###### middleName (String)

Middle name

More information:

- Maximum length: 32 characters

###### lastName (String, REQUIRED)

Last name

More information:

- Maximum length: 32 characters

###### fullName (String)

Full name

More information:

- Maximum length: 128 characters

###### buyerPhoneNo (String)

The mobile phone number of the buyer.

> **Note**: Specify this parameter when one of the following conditions is met:
>
> -   When you require risk control.
> -   Specify this parameter to improve payment success rates when using the EasySafePay product. The formats for different payment methods are as follows:
>
> -   Alipay HK
>
> -   With 852 prefix, for example, "852-12345678"
> -   With 86 prefix, for example, "86-12312345678"
>
> -   DANA
>
> -   With 62 prefix, for example, "62-85691234567"
>
> Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

More information:

- Maximum length: 24 characters

###### buyerEmail (Email)

The email of the buyer.

> **Note**: Specify this parameter when one of the following conditions is met:
>
> -   When you require risk control.
> -   Specify this parameter to improve payment success rates when using the EasySafePay product.
>
> Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

More information:

- Maximum length: 64 characters

###### buyerRegistrationTime (Datetime)

The time when the buyer registered your account.

> Note: Specify this parameter if you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.

More information:

- Maximum length: 64 characters
- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

#### paymentRequestId (String, REQUIRED)

The unique ID assigned by a merchant to identify a payment request.

More information:

- Maximum length: 64 characters

#### paymentAmount (Amount, REQUIRED)

The payment amount that the merchant requests to receive in the order currency.

##### currency (String, REQUIRED)

The transaction currency, which is a 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.

More information:

- Maximum length: 3 characters

##### value (Integer, REQUIRED)

The value of the amount as a positive integer in the smallest currency unit. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to `100`; or if the currency is JPY and the amount is ￥1, set the value of this parameter to `1`. 

For details about the smallest currency unit, see [Smallest unit of the currency](https://docs.antom.com/ac/ref/cc.md#ONkIe) .

For details about the minimum payment amount allowed for each payment method, see [Minimum amount rules](https://docs.antom.com/ac/ref/cc.md#q9R5A).

> Due to the currency practices in Indonesia, when the currency is IDR, round the amount with banker's rounding and fix the last two digits of this parameter as `00`.

More information:

- Value range: 1 - unlimited

#### settlementStrategy (SettlementStrategy, REQUIRED)

The settlement strategy for the payment request.

##### settlementCurrency (String)

The ISO currency code of the currency that the merchant wants to be settled against. The field is required if the merchant signed up for multiple currencies to settle.

More information:

- Maximum length: 3 characters

#### paymentMethod (PaymentMethod, REQUIRED)

The payment method that is used to collect the payment by the merchant or acquirer.

##### paymentMethodType (String, REQUIRED)

The payment method type that is included in payment method options.

More information:

- Maximum length: 64 characters

##### paymentMethodId (String)

The unique ID that is used to identify a payment method. The value of this parameter is that of _accessToken_ from the [**notifyAuthorization**](https://docs.antom.com/ac/ams/notifyauth.md) API.

> Note: Specify this parameter for subsequent EasySafePay payments.

More information:

- Maximum length: 128 characters

#### agreementInfo (AgreementInfo)

Authorization information about EasySafePay payments.

> Note: Specify this parameter to obtain an access token for the first-time EasySafePay payment only.

##### authState (String)

The unique ID generated by the merchant to initiate an EasySafePay authorization.

> Note: Specify this parameter to obtain an access token for the first-time EasySafePay payment only.

More information:

- Maximum length: 256 characters

##### userLoginId (String)

The login ID that the user used to register in the payment method client. The login ID can be the user's email address or phone number.

> Note: Specify this parameter to free users from manually entering their login IDs.

More information:

- Maximum length: 64 characters

#### paymentSessionExpiryTime (Datetime)

The specific date and time after which the payment session will expire. The default expiration time is 1 hour after the session creation. For example, if the session is created at 2023-7-27T12:00:01+08:30, the session expiration time is 2023-7-27T13:00:01+08:30.

> Note: Specify this parameter if you want to use a payment session expiration time that differs from the default time. The specified expiration time must be 0 to 1 hour after session creation.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

#### paymentNotifyUrl (URL, REQUIRED)

The URL that is used to receive the payment result notification.

More information:

- Maximum length: 2048 characters

#### paymentRedirectUrl (URL, REQUIRED)

The merchant page URL that the user is redirected to after the payment is completed.

> **Note**: The maximum length of this parameter is 255 when the value of _paymentMthodType_ is `PAYPAY`.

More information:

- Maximum length: 2048 characters

#### productCode (String, REQUIRED)

Represents the payment product that is being used. The value is fixed as `AGREEMENT_PAYMENT` .

#### productScene (String, REQUIRED)

The value is fixed as `EASY_PAY`, which indicates an EasySafePay payment.

More information:

- Maximum length: 32 characters

#### paymentExpiryTime (Datetime)

The payment expiration time. Use the parameter to specify the timeout duration after Antom confirms the order. If not specified, the default timeout will apply.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

## Response parameters

#### result (Result, REQUIRED)

The result of the API call. If this API is successfully called, the payment session is created successfully.

##### resultCode (String, REQUIRED)

Result code. The result code that might be returned are listed in the **Result/Error codes** table on this page.

More information:

- Maximum length: 64 characters

##### resultStatus (String, REQUIRED)

Result status. Valid values are:

-   `S`: Indicates that the result status is successful.
-   `F`: Indicates that the result status is failed. 
-   `U`: Indicates that the result status is unknown.

##### resultMessage (String, REQUIRED)

Result message that explains the result code.

More information:

- Maximum length: 256 characters

#### paymentSessionId (String, REQUIRED)

The encrypted ID that is assigned by Antom to identify a payment session.

More information:

- Maximum length: 64 characters

#### paymentSessionData (String, REQUIRED)

The encrypted payment session data. Pass the data to your front end to initiate the client-side SDK.

More information:

- Maximum length: 4096 characters

#### paymentSessionExpiryTime (Datetime, REQUIRED)

The date and time when the payment session expires.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

## More information

About the _order_ field: Antom does not verify the consistency of the amount in the _order_ field and the amount in the payment request. The order information is not applied in fund operations either. This field is mainly used for risk control, supervision, regulatory reporting, and consumption records display. Use the _env_ field if the risk control capability provided by Antom is needed.

#BUTTON#Sample for the order field#
{
 "order": {
 "referenceOrderId": "102775745075669",
 "orderDescription": "Mi Band 3 Wrist Strap Metal Screwless Stainless Steel For Xiaomi Mi Band 3 ",
 "orderAmount": {
 "value": "500",
 "currency": "USD"
        },
 "goods": \[{
 "referenceGoodsId": "102775745075669",
 "goodsName": "xxx goods",
 "goodsUnitAmount": {
 "currency": "USD",
 "value": "498"
            },
 "goodsQuantity": "1"
        }\],
 "shipping": {
 "shippingName": {
 "fullName": "Bob Day"
            },
 "shippingAddress": {
 "region": "US",
 "state": "California",
 "city": "San Mateo",
 "address1": "400 El Camino Real",
 "address2": "suit 107",
 "zipCode": "95014"
            },
 "shippingCarrier": "USPS",
 "shippingPhoneNo": "9093749555"
        },
 "buyer": {
 "referenceBuyerId": "bob@gmail.com",
 "buyerName": {
 "fullName": "Bob Day"
            },
 "buyerPhoneNo": "+86 18888888888",
 "buyerEmail": "bob@gmail.com"
        }
    }
}

## Result/Error codes

| Code | Value | Message | Further action |
| --- | --- | --- | --- |
| SUCCESS | S | Success | The payment session is successfully created. No further action is needed. |
| PARAM_ILLEGAL | F | The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong. | Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid. |
| PROCESS_FAIL | F | A general business failure occurred. | Do not retry. Human intervention is usually needed. It is recommended that you contact Antom Technical Support to troubleshoot the issue. |
| UNKNOWN_EXCEPTION | U | An API call has failed, which is caused by unknown reasons. | Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support. |

## Request

### AUTHORIZE_AND_PAY

```json
{
  "env": {
    "osType": "ANDROID",
    "terminalType": "APP"
  },
  "agreementInfo": {
    "authState": "authState_293111782543453",
    "userLoginId": "852-91234567"
  },
  "order": {
    "buyer": {
      "referenceBuyerId": "yourBuyerId"
    },
    "orderAmount": {
      "currency": "USD",
      "value": "98080"
    },
    "orderDescription": "antom api testing order",
    "referenceOrderId": "1a57b8cd-9a25-4d44-94f7-3467a4ebe532"
  },
  "paymentAmount": {
    "currency": "USD",
    "value": "98080"
  },
  "paymentMethod": {
    "paymentMethodType": "ALIPAY_HK",
    "paymentMethodId": "28288803002561481743389798000V30mFAqYku171000049"
  },
  "paymentNotifyUrl": "http://www.yourNotifyUrl.com",
  "paymentRedirectUrl": "http://www.yourRedirectUrl.com",
  "paymentRequestId": "paymentRequestId_2111197385743854",
  "productCode": "AGREEMENT_PAYMENT",
  "productScene": "EASY_PAY",
  "settlementStrategy": {
    "settlementCurrency": "USD"
  }
}
```

### SUBSEQUENT_PAYMENT_WITH_TOKEN

```json
{
  "order": {
    "buyer": {
      "referenceBuyerId": "referenceBuyerId002"
    },
    "orderAmount": {
      "currency": "CNY",
      "value": "30000"
    },
    "orderDescription": "orderDescription002",
    "referenceOrderId": "referenceOrderId002"
  },
  "paymentAmount": {
    "currency": "CNY",
    "value": "30000"
  },
  "paymentMethod": {
    "paymentMethodId": "282888030024702917429699670006prapf6Os1171000349",
    "paymentMethodType": "ALIPAY_HK"
  },
  "paymentNotifyUrl": "http://gol.alipay.net:8080/amsdemo/record/notify?env=main_pre&paymentMethodType=ALIPAY_CN",
  "paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result",
  "paymentRequestId": "paymentRequestId002",
  "productCode": "AGREEMENT_PAYMENT",
  "productScene": "EASY_PAY",
  "settlementStrategy": {
    "settlementCurrency": "USD"
  }
}
```

## Response

```json
{
  "paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
  "paymentSessionExpiryTime": "2023-04-06T03:28:49+08:00",
  "paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
```