# pay (Tokenized Payment) > After the user agrees to authorize, use this API to initiate Tokenized Payment and process payment results according to the status and operation instructions returned by Antom. `POST /v1/payments/pay` After the user agrees to authorize, use this API to initiate Tokenized Payment and process payment results according to the status and operation instructions returned by Antom. # 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 #### 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 acquiring 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). Notes: For details about the smallest currency unit, see [Smallest unit of the currency](https://global.alipay.com/docs/ac/ref/cc#ONkIe). More information: - Value range: 0 - 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 information, including the ID, name, price, and quantity of the goods in the order. > **Note**: Specify this field if you have the goods information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would 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) A categorization of the goods type. More information: - Maximum length: 64 characters ###### goodsUnitAmount (Amount) Price of goods. > **Note**: Specify this field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would 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). Notes: For details about the smallest currency unit, see [Smallest unit of the currency](https://global.alipay.com/docs/ac/ref/cc#ONkIe). More information: - Value range: 1 - unlimited ###### goodsQuantity (Integer) Quantity of goods. > **Note**: Specify this field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. More information: - Value range: 1 - unlimited ##### shipping (Shipping) Shipping information, including information about the recipient (name, phone number, and shipping address), and shipping service provider. > **Note**: Specify this field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. ###### shippingName (UserName) Name of the recipient. > **Note**: Specify this field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would 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 field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. ###### region (String, REQUIRED) The 2-letter country/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, USPS, etc. > **Note**: Specify this field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. More information: - Maximum length: 128 characters ###### shippingPhoneNo (String) The phone number of a recipient (including extension). > **Note**: Specify this field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. More information: - Maximum length: 16 characters ##### buyer (Buyer) Buyer information, including the ID, name, phone number, and email of the buyer. > **Note**: Although this field is optional, it is highly recommended to specify this field because this field is used for risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. ###### referenceBuyerId (String) The unique ID to identify the buyer. > **Note**: Specify this field when you have the risk control requirement. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. More information: - Maximum length: 64 characters ###### buyerName (UserName) Name of the buyer. > **Note**: Specify this field when you have the risk control requirement. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would 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) 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) 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 ##### merchant (Merchant) Information about the secondary merchant. > **Note**: Specify this field if you are an acquirer that has secondary merchants. ###### referenceMerchantId (String, REQUIRED) The ID to identify the merchant that directly provides services or goods to the customer. More information: - Maximum length: 32 characters ###### merchantMCC (String) The merchant category code, which is a 4-digit number listed in [MCC codes](https://docs.antom.com/ac/ref/mcccodes.md). > **Note**: Specify this field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. More information: - Maximum length: 32 characters ###### merchantName (String) The merchant name. > Note: Specify this field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. More information: - Maximum length: 256 characters ###### merchantDisplayName (String) The merchant name to be displayed. > **Note**: Specify this field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. More information: - Maximum length: 64 characters ###### merchantAddress (Address) The merchant address information. > **Note**: Specify this field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. ###### region (String, REQUIRED) The 2-letter country/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 ###### merchantRegisterDate (Datetime) Merchant registration date. > **Note**: Specify this field if you have the information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. 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". ##### env (Env) Information about the environment where the order is placed, such as the device information. > **Note**: Specify this parameter when one of the following conditions is met: > > - When you have the environment information. > - When the request is sent by a mini program. > - When the transaction scenario is EasySafePay. > > Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates. ###### terminalType (String) Terminal type of which the merchant service applies to. Valid values are: - `WEB`: The client-side terminal type is a website that is opened via a PC browser. - `WAP`: The client-side terminal type is an HTML page that is opened via a mobile browser. - `APP`: The client-side terminal type is a mobile application. - `MINI_APP`: The terminal type of the merchant side is a mini program on the mobile phone. > **Note**: This parameter is required when you signed the EasySafePay contract offline. ###### osType (String) OS type. Valid values are:   - `IOS`: indicates the operating system is Apple's iOS. - `ANDROID`: indicates the operating system is Google's Android. > **Note**: Specify this parameter when one of the following conditions is met: > > - This parameter is required when _terminalType_ is `APP`, `MINI_APP` or `WAP`. > - This parameter is required when you signed the EasySafePay contract offline. ###### userAgent (String) This field is used to indicate the user identity by containing the identifier of the payment method used by the user. > **Note**: Specify this field if you can obtain the information from the user. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. More information: - Maximum length: 1024 characters ###### deviceTokenId (String) Token identifier of the device. > **Note**: Specify this parameter when one of the following conditions is met: > > - When you integrate with the Antom Device Fingerprint client, which is an SDK or a JavaScript library that is used to collect device-related information, such as _osType_, _deviceLanguage_, _deviceId_, _websiteLanguage_, and _userAgent_. > - When you has signed the EasySafePay contract offline. It is recommended that you integrate the risk control SDK and retrieve the deviceTokenId from it. > > The device-related information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates. For more information about the Antom Device Fingerprint client, contact Antom Technical Support. More information: - Maximum length: 64 characters ###### clientIp (String) IP address of the client device. > **Note**: Specify this parameter when one of the following conditions is met: > > - When you require risk control. > - When the value of _paymentMethodType_ is `CARD`. > - When the value of _paymentMethodType_ is `BLIK` and you collect the information of _blikCode_. > - This parameter is required when you signed the EasySafePay contract offline. > > 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 ###### cookieId (String) The cookie ID of the buyer. > **Note**: Specify this field if you can obtain the information from the user. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates. More information: - Maximum length: 64 characters ###### extendInfo (String) Extended information. > **Note**: Specify this field if you need to use the extended information. More information: - Maximum length: 2048 characters ###### deviceId (String) The unique ID of the device the user places an order with. > **Note**: Specify this parameter when one of the following conditions is met: > > - When you require risk control. > - This parameter is required when you signed the EasySafePay contract offline. > > This parameter can be used to build a trusted relationship between users and commonly used devices, thereby reducing risk control interruptions and increasing the payment success rate. More information: - Maximum length: 64 characters ##### extendInfo (ExtendInfo) Extended information data, including information for special use cases. > **Note**: Specify this field when you need to use the extended information. More information: - Maximum length: 2048 characters ###### chinaExtraTransInfo (ChinaExtraTransInfo) Extra information about the transaction. > **Note**: Specify this field for transactions to Alipay. ###### admissionNoticeUrl (URL) The school admission notice URL. Mulitple URLs are delimited by '|'. When _businessType_\=3, this field needs to be specified. More information: - Maximum length: 1000 characters ###### businessType (String, REQUIRED) The business type. Valid values are: - `1`: Hotel - `2`: Air Flight - `3`: Study Abroad - `4`: Trade - `5`: Other   Multiple business types are delimited by "|". More information: - Maximum length: 16 characters ###### checkinTime (Datetime) The hotel check-in time in the format of yyyy-MM-dd and in the UTC+8 timezone. Multiple hotel check-in times are delimited by '|'. When _businessType_\=1, this field needs to be specified. More information: - Maximum length: 1000 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". ###### departureTime (Datetime) The flight departure time in the format of yyyy-MM-dd HH:mm. Multiple flight departure times are delimited by '|'. When _businessType_\=2, this field needs to be specified. More information: - Maximum length: 1000 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". ###### flightNumber (String) The flight number. Multiple flight numbers are delimited by '|'. When _businessType_\=2, this field needs to be specified. More information: - Maximum length: 1000 characters ###### goodsInfo (String) Goods information that includes SKU names and corresponding quantities, in the format of SKU\_name^quantity. If more than one goods exists, separate values with a vertical bar (|). When _businessType_\=4, this field needs to be specified. ###### hotelName (String) The hotel name. Multiple hotel names are delimited by '|'. When _businessType_\=1, this field needs to be specified. More information: - Maximum length: 1000 characters ###### totalQuantity (Integer) Total quantities of all goods in one order. When _businessType_\=4, this field needs to be specified. More information: - Value range: 0 - unlimited #### paymentRequestId (String, REQUIRED) The unique ID that is assigned by a merchant to identify a payment request. More information: - This field is an API idempotency field.The merchant uses the paymentRequestId field for idempotency control. For payment requests that are initiated with the same value of paymentRequestId and reach a final status (S or F), the same result is to be returned for the request. - Maximum length: 64 characters #### paymentAmount (Amount, 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. ##### 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 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). > **Note**: 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) The settlement strategy for the payment request. ##### settlementCurrency (String) The ISO currency code of the currency that the merchant wants to be settled against. > **Note**: Specify this parameter when you signed multiple settlement currencies when signing with Antom. 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) Payment method type, used for specifying the wallet type. By specifying this field, it indicates that the payment is made by using the specific wallet. See [Payment methods](https://docs.antom.com/ac/pm/enumeration_values.md) to check the valid values. More information: - Maximum length: 64 characters ##### paymentMethodId (String, REQUIRED) The unique ID of the payment method that belongs to a buyer. The value of this field is the value of _accessToken_ obtained by calling the [**applyToken**](https://docs.antom.com/ac/ams/accesstokenapp.md) API. More information: - Maximum length: 128 characters ##### extendInfo (String) Extended information. > **Note**: Specify this field if you need to use the extended information. More information: - Maximum length: 2048 characters ##### paymentMethodMetaData (PaymentMethodMetaData) Additional information required for certain payment methods. **Scenario: Alipay** (Alipay) ###### recurringType (String) The recurring type for the payment. Valid values are: - `SCHEDULED`: Indicates a regular automated deduction payment. - `UNSCHEDULED`: Indicates an irregular automated deduction payment. If the value of this parameter is empty or you do not specify this parameter, the payment is not an automated deduction and the payer will be included in the payment process. > Note: Specify this parameter when you has signed the EasySafePay contract offline and the payment is a merchant-initiated transaction (MIT). **Scenario: AlipayHK** (AlipayHK) ###### recurringType (String) The recurring type for the payment. Valid values are: - `SCHEDULED`: Indicates a regular automated deduction payment. - `UNSCHEDULED`: Indicates an irregular automated deduction payment. If the value of this parameter is empty or you do not specify this parameter, the payment is not an automated deduction and the payer will be included in the payment process. > Note: Specify this parameter when you has signed the EasySafePay contract offline and the payment is a merchant-initiated transaction (MIT). **Scenario: DANA** (DANA) ###### recurringType (String) The recurring type for the payment. Valid values are: - `SCHEDULED`: Indicates a regular automated deduction payment. - `UNSCHEDULED`: Indicates an irregular automated deduction payment. If the value of this parameter is empty or you do not specify this parameter, the payment is not an automated deduction and the payer will be included in the payment process. > Note: Specify this parameter when you has signed the EasySafePay contract offline and the payment is a merchant-initiated transaction (MIT). **Scenario: GCash** (GCash) ###### recurringType (String) The recurring type for the payment. Valid values are: - `SCHEDULED`: Indicates a regular automated deduction payment. - `UNSCHEDULED`: Indicates an irregular automated deduction payment. If the value of this parameter is empty or you do not specify this parameter, the payment is not an automated deduction and the payer will be included in the payment process. > Note: Specify this parameter when you has signed the EasySafePay contract offline and the payment is a merchant-initiated transaction (MIT). **Scenario: Touch'n Go eWallet** (Touch'n Go eWallet) ###### recurringType (String) The recurring type for the payment. Valid values are: - `SCHEDULED`: Indicates a regular automated deduction payment. - `UNSCHEDULED`: Indicates an irregular automated deduction payment. If the value of this parameter is empty or you do not specify this parameter, the payment is not an automated deduction and the payer will be included in the payment process. > Note: Specify this parameter when you has signed the EasySafePay contract offline and the payment is a merchant-initiated transaction (MIT). **Scenario: TrueMoney** (TrueMoney) ###### recurringType (String) The recurring type for the payment. Valid values are: - `SCHEDULED`: Indicates a regular automated deduction payment. - `UNSCHEDULED`: Indicates an irregular automated deduction payment. If the value of this parameter is empty or you do not specify this parameter, the payment is not an automated deduction and the payer will be included in the payment process. > Note: Specify this parameter when you has signed the EasySafePay contract offline and the payment is a merchant-initiated transaction (MIT). #### creditPayPlan (CreditPayPlan) The credit payment plan information for this payment. > **Note**: Specify this field if you want to support installment payment and contact Antom technical support for details on how to offer installment payments. ##### installmentNum (String, REQUIRED) The number of installments within a month. More information: - Maximum length: 8 characters ##### creditPayFeeType (String) The value of this field is `PERCENTAGE`, which indicates that the fee is described in percentage with 1 - 3 digits. For example, 5 means 5%, 100 means 100%. > **Note**: Specify this field when you want the fee information to be expressed in percentage. ##### feePercentage (Integer) This field is determined by the sellers' liability. For example: 0 indicates the seller is not liable for any fee. 100 indicates the seller pays 100% of the fee. > **Note**: Specify this field when the value of _creditPayFeeType_ is `PERCENTAGE`. More information: - Value range: 0 - 100 #### appId (String) The unique ID that is assigned by Antom to identify the mini program app. > **Note**: Specify this field when _terminalType_ is `MINI_APP`. More information: - Maximum length: 32 characters #### paymentExpiryTime (Datetime) The payment expiration time is a specific time after which the payment will expire and the acquirer or merchant must terminate the order processing. A default payment expiration time is determined by the contract. > **Notes**:  > > - Specify this field if you want to use a payment expiration time that differs from the default time. The specified payment expiration time must be less than one minute after the payment request is sent and must follow the correct format. > - Usually for Tokenized Payment, the default payment expiration time in the contract is one minute after the payment request is sent. For example, the request is sent when the time is 2019-11-27T12:00:01+08:30, the payment expiration time is 2019-11-27T12:01:01+08:30. 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) The URL that is used to receive the payment result notification. > **Note**: Specify this field if you want to receive an asynchronous notification of the Tokenized Payment result. You can also set the URL to receive the payment result notification in Antom Dashoard. If the payment notification URL is specified in both the request and Antom Dashboard, the value specified in the request takes precedence. More information: - Maximum length: 2048 characters #### productCode (String, REQUIRED) Represents the payment product that is being used, which is stipulated in the contract. For Tokenized Payment, the value is fixed as `AGREEMENT_PAYMENT`. #### 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) A unique request ID generated by the merchant to identify the consultation request. This field must match the one in the redirect link when the user grants authorization. > **Note**: Specify this parameter to obtain an access token for the first-time EasySafePay payment only. More information: - Maximum length: 256 characters ## Response parameters #### result (Result, REQUIRED) Indicates whether this API is called successfully. If this API is successfully called, it means the Tokenized Payment is completed 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 payment succeeded. - `F`: Indicates that the payment failed. - `U`: Indicates that the payment status is unknown. ##### resultMessage (String, REQUIRED) Result message that explains the result code. More information: - Maximum length: 256 characters #### paymentRequestId (String) The unique ID that is assigned by a merchant to identify a payment request.  Note: This field is returned when the API is called successfully. More information: - Maximum length: 64 characters #### paymentId (String) The unique ID that is assigned by Antom to identify a payment. > Note: This field is returned when the API is called successfully. More information: - Maximum length: 64 characters #### paymentAmount (Amount) The payment amount that the merchant requests to receive in the order currency. > **Note**: This field is returned when the API is called successfully. ##### 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). Notes: For details about the smallest currency unit, see [Smallest unit of the currency](https://global.alipay.com/docs/ac/ref/cc#ONkIe). More information: - Value range: 1 - unlimited #### paymentTime (Datetime) The date and time when the payment reaches a final state of success. > **Note**: This field is returned when the API is called successfully. 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". #### paymentCreateTime (Datetime) The date and time when the payment is created. > **Note**: This field is returned when the API is called successfully. 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". #### pspCustomerInfo (PspCustomerInfo) The customer information of the digital wallets. > **Note**: This field is returned when the digital wallets can provide the related information. ##### pspName (String) The name of the digital wallets. > **Note**: This field is returned when the digital wallets supports providing the related information. More information: - Maximum length: 64 characters ##### pspCustomerId (String) The customer ID of the digital wallets. > **Note**: This field is returned when the digital wallets support providing the related information. More information: - Maximum length: 64 characters ##### displayCustomerId (String) The customer ID used for display. For example, _loginId_. > **Note**: This field is returned when the digital wallets support providing the related information. More information: - Maximum length: 64 characters #### grossSettlementAmount (Amount) The value of this field equals to transaction amount multiplied by the value of _settlementQuote_. This field is returned when the currency exchange is predetermined and the exchange rate is locked at the time of transaction. ##### 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 zero-decimal currency). Note: For details about the smallest currency unit, see [Smallest unit of the currency](https://global.alipay.com/docs/ac/ref/cc#ONkIe). More information: - Value range: 1 - unlimited #### settlementQuote (Quote) The exchange rate between the settlement currency and transaction currency. This field is returned when _grossSettlementAmount_ is returned. ##### guaranteed (Boolean) Guaranteed exchange rate available for payment. ##### quoteCurrencyPair (String, REQUIRED) The exchange rate between settlement currency and transaction currency. Two currencies are separated with a slash and use the 3-letter [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. More information: - Maximum length: 16 characters ##### quoteExpiryTime (Datetime) Expiration time of the exchange rate. 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". ##### quoteId (String) The unique ID that is assigned by Antom to identify an exchange rate. More information: - Maximum length: 64 characters ##### quotePrice (Decimal, REQUIRED) The exchange rate used when a currency conversion between settlement currency and transaction currency occurs. More information: - Value range: 0 - unlimited ##### quoteStartTime (Datetime) Effective time of the exchange rate. 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". #### applinkUrl (String) The URL that redirects users to open an app when the target app is installed, or to open a WAP page when the target app is not installed. - For Android, the URL is a Native App Link. - For iOS, the URL is a Universal Link. > **Note**: At least one of _schemeUrl_, _applinkUrl,_ and _normalUrl_ is to be returned when one of the following conditions is met: > > - When the value of _resultCode_ is `PAYMENT_IN_PROCESS`. > - When you has signed the EasySafePay contract offline. > - When the value of _paymentMethodId_ is empty (indicating a non-tokenized payment). > - When the payment method used for the transaction supports EasySafePay. More information: - Maximum length: 2048 characters #### normalUrl (String) The URL that redirects users to a WAP or Web page in the default browser or the embedded WebView. > **Note**: At least one of _schemeUrl_, _applinkUrl,_ and _normalUrl_ is to be returned when one of the following conditions is met: > > - When the value of _resultCode_ is `PAYMENT_IN_PROCESS`. > - When you has signed the EasySafePay contract offline. > - When the value of _paymentMethodId_ is empty (indicating a non-tokenized payment). > - When the payment method used for the transaction supports EasySafePay. More information: - Maximum length: 2048 characters #### schemeUrl (String) The URL scheme that redirects users to open an app in an Android or iOS system when the target app is installed. > **Note**: At least one of _schemeUrl_, _applinkUrl,_ and _normalUrl_ is to be returned when one of the following conditions is met: > > - When the value of _resultCode_ is `PAYMENT_IN_PROCESS`. > - When you has signed the EasySafePay contract offline. > - When the value of _paymentMethodId_ is empty (indicating a non-tokenized payment). > - When the payment method used for the transaction supports EasySafePay. More information: - Maximum length: 2048 characters ## More information  This section gives additional information about other parameters. See the following list for details: - _order_: 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"` `},` `"extendInfo": "{ \"chinaExtraTransInfo\":{ \"businessType\":\"1|2|3|4|5\", \"hotelName\":\"Holiday Inn San Jose|Hyatt Resort San Mateo\", \"checkinTime\":\"2018-10-21|2018-10-30\", \"checkoutTime\":\"2018-10-24|2018-11-03\", \"flightNumber\":\"UA898|CA986\", \"departureTime\":\"2018-10-22 20:49|2018-10-23 04:50\", \"admissionNoticeUrl\":\"https://www.iconfont.cn/search/index?test\"}}"` `}` `}` - _paymentTime_: The successful execution time of this payment by Antom, that is, the date and time when the payment reaches a final state of success. This value is used as the start time of the subsequent cancellable and refundable time. For example, if the refundable time is 6 months, the final time to accept the refund is _paymentTime_ plus 6 months. ## Result process logic For different request results, different actions are to be performed. See the following list for details: - If the value of _result.resultStatus_ is `S`, the payment succeeded. - If the value of _result.resultStatus_ is `F`, the payment failed. - If the value of _result.resultStatus_ is `U`, the payment status is unknown. You can wait for the asynchronous notification of the payment result and call the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) interface to inquire about the payment result constantly until getting the final payment result. If you cannot receive the asynchronous notification or get a confirmative result (`S` or `F`) from the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) response, terminate the transaction by calling the [**cancel**](https://docs.antom.com/ac/ams/paymentc_online.md) API to keep the transaction status consistent between you and the user. ## Result/Error codes | Code | Value | Message | Further action | | --- | --- | --- | --- | | SUCCESS | S | Success | The payment is successful, no further action is needed. | | ACCESS_DENIED | F | Access is denied. | Contact Antom Technical Support for detailed reasons. | | CURRENCY_NOT_SUPPORT | F | The currency is not supported. | Contact Antom Technical Support for detailed reasons. | | EXPIRED_CODE | F | The payment code is expired. | The user needs to refresh the payment code. | | INVALID_ACCESS_TOKEN | F | The access token is expired, revoked, or does not exist. | Check whether the access token is expired, revoked, or does not exist. Re-sign the contract and re-initiate the authorization signing process. | | INVALID_CONTRACT | F | The parameter values in the contract do not match those in the current transaction. | Check whether the parameter values in the contract match those in the current transaction. If the values match, contact Antom Technical Support to troubleshoot the issue. | | INVALID_MERCHANT_STATUS | F | The merchant status is abnormal because restrictions exist. | Contact Antom Technical Support for detailed reasons. | | INVALID_PAYMENT_CODE | F | The payment code cannot be accepted by Alipay+. | Choose other payment methods. Contact Antom Technical Support if the payment method is supported. | | INVALID_PAYMENT_METHOD_META_DATA | F | The payment method metadata is invalid. | Check whether payment method metadata is correct. If correct, contact Antom Technical Support. | | KEY_NOT_FOUND | F | The private key or public key of Antom or the merchant is not found. | Check whether the private key or public key exists. If not, upload the private key in Antom Dashboard. | | MERCHANT_KYB_NOT_QUALIFIED | F | The payment failed because of the merchant's KYB status. The merchant is either not KYB compliant, or the KYB status is not qualified for this transaction. | Contact Antom Technical Support for detailed reasons. | | MERCHANT_NOT_REGISTERED | F | The merchant is not registered. | Please register the merchant by using the registration interface. Contact Antom Technical Support if failed to call the registration interface. | | NO_INTERFACE_DEF | F | API is not defined. | Check whether the URL is correct. Please refer to the endpoint in the API documentation. | | NO_PAY_OPTIONS | F | No payment options are available. | Contact Antom Technical Support for detailed reasons. | | ORDER_IS_CANCELED | F | The request you initiated has the same paymentRequestId as the previously paid transaction, which is canceled. | Use a new paymentRequestId to initiate the payment again. | | ORDER_IS_CLOSED | F | The request you initiated has the same paymentRequestId as that of the existed transaction, which is closed. | Use a new paymentRequestId to initiate the payment again. | | ORDER_NOT_EXIST | F | The order does not exist. | Check whether paymentId is correct. | | 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. | | PAYMENT_AMOUNT_EXCEED_LIMIT | F | The payment amount is greater than the maximum amount allowed by the contract or wallet. | Check whether the payment amount exceeds the limit or use a lower amount and try again. Contact Antom technical support to know the specific limitation. | | PAYMENT_COUNT_EXCEED_LIMIT | F | The maximum number of payments exceeds the limit that is specified by the wallet. | Contact Antom Technical Support to know the specific limitation. | | PAYMENT_NOT_QUALIFIED | F | The merchant is not qualified to pay because the merchant is not registered, does not have a contract for Tokenized Payment, or is forbidden to make a payment. | Contact Antom Technical Support for detailed reasons. | | 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. | | REPEAT_REQ_INCONSISTENT | F | The amount or currency is different from the previous request. | Ensure all the fields in the requests are the same or use a new paymentRequestId to initiate the payment again. | | RISK_REJECT | F | The request is rejected because of the risk control. | Prompt the user that the request is rejected because the risk control failed. | | SETTLE_CONTRACT_NOT_MATCH | F | No matched settlement contract can be found. | Check the following for a solution: Specify one settlement currency from the multiple currencies that the merchant signed up for. Check if the settlement currency is specified in the settlement contracts. The merchant didn't sign a settlement contract. Contact Antom Technical Support. | | SYSTEM_ERROR | F | A system error occurred. | Do not retry, and contact Antom Technical Support for more details. | | USER_AMOUNT_EXCEED_LIMIT | F | The payment amount exceeds the user payment limit. | Create a new payment by using an amount less than or equal to the account's available balance, or contact Antom Technical Support. | | USER_BALANCE_NOT_ENOUGH | F | The payment cannot be completed because the user balance in the corresponding payment method is not enough. | Please top up the account or choose other payment methods. | | USER_KYC_NOT_QUALIFIED | F | The payment failed because of the user's KYC status. The user is either not KYC compliant, or the KYC status is not qualified for this transaction (for example, limitations on the payment amount or product information). | Complete the KYC verification first. | | USER_NOT_EXIST | F | The user does not exist on the wallet side. | Contact Antom Technical Support for detailed reasons. | | USER_PAYMENT_VERIFICATION_FAILED | F | User fails to pass the payment verification in the methods like OTP, PIN, and so on. | Contact Antom Technical Support to know the specific reasons. | | USER_STATUS_ABNORMAL | F | The user status is abnormal on the wallet side. | Contact Antom Technical Support to know the specific reasons. | | PAYMENT_IN_PROCESS | U | The payment is being processed. | Wait for the asynchronous notification or call the inquiryPayment interface to query the final payment status. | | REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support. | | UNKNOWN_EXCEPTION | U | An API call has failed, which is caused by unknown reasons. | Call the inquiryPayment interface to query the final payment status. If the issue is not resolved, contact Antom Technical Support. | | VERIFY_TIMES_EXCEED_LIMIT | F | The current verification code failed to pass the payment verification too many times. | The user must get a new verification code. | | VERIFY_UNMATCHED | F | The verification code is invalid. | The user must get a new verification code. | ## Request ```json { "settlementStrategy": { "settlementCurrency": "USD" }, "order": { "orderAmount": { "currency": "PHP", "value": "1100" }, "orderDescription": "Mika's coffee shop", "referenceOrderId": "ORDER_2020070316170XXXX" }, "paymentAmount": { "currency": "PHP", "value": "1100" }, "paymentMethod": { "paymentMethodId": "28101003_20200703duEWYqq9p9RSzGbOisAnJ4NCKygW3KQSMYouR73Vuqn088630526XXXX", "paymentMethodType": "GCASH" }, "paymentRequestId": "AGREEMENT_PAYMENT_REQUEST_2020070316170XXXX", "productCode": "AGREEMENT_PAYMENT" } ``` ## Response ### SUCCESS ```json { "paymentAmount": { "currency": "PHP", "value": "1100" }, "paymentCreateTime": "2020-07-03T01:17:50-07:00", "paymentId": "2020070311401080010018840027964XXXX", "paymentRequestId": "AGREEMENT_PAYMENT_REQUEST_2020070316170XXXX", "result": { "resultCode": "SUCCESS", "resultMessage": "Success", "resultStatus": "S" } } ```