Latest release: 1.7.0
Use Python 3.9.2 or later; a maintained Python release is recommended.
The SDK uses Python 3.9+ type annotations, and its cryptography dependency
excludes Python 3.9.0 and 3.9.1. Use a virtual environment and ensure python
refers to that interpreter.
python -m pip install --upgrade global-open-sdk-pythonFor Meter HTTP/2, install the optional dependencies with
python -m pip install --upgrade "global-open-sdk-python[http2]".
- RSA: follow the configuration and inline example below.
- API Key (limited availability): follow the setup guide and run the sandbox example.
- Browse more examples and the API documentation.
RSA and API Key clients share request/response models. File uploads and notification verification still require RSA credentials.
Before using the RSA client, prepare these values from your Antom integration:
gatewayUrl=your_regional_https_gateway
clientId=your_client_id
merchantPrivateKey=your_merchant_private_key
alipayPublicKey=your_antom_public_keyThe examples read them from ANTOM_GATEWAY_URL, ANTOM_CLIENT_ID,
ANTOM_MERCHANT_PRIVATE_KEY, and ANTOM_PUBLIC_KEY, respectively.
Keep keys in server-side configuration. Replace sample order data and callback
URLs with your own values before sending a request.
Save as payment_example.py and configure the four environment variables above.
import os
import uuid
from com.alipay.ams.api.model.merchant import Merchant
from com.alipay.ams.api.model.amount import Amount
from com.alipay.ams.api.model.settlement_strategy import SettlementStrategy
from com.alipay.ams.api.model.order import Order
from com.alipay.ams.api.model.product_code_type import ProductCodeType
from com.alipay.ams.api.model.payment_method import PaymentMethod
from com.alipay.ams.api.model.env import Env
from com.alipay.ams.api.model.goods import Goods
from com.alipay.ams.api.model.terminal_type import TerminalType
from com.alipay.ams.api.model.os_type import OsType
from com.alipay.ams.api.model.result_status_type import ResultStatusType
from com.alipay.ams.api.default_alipay_client import DefaultAlipayClient
from com.alipay.ams.api.request.pay.alipay_pay_request import AlipayPayRequest
from com.alipay.ams.api.response.pay.alipay_pay_response import AlipayPayResponse
MERCHANT_PRIVATE_KEY = os.environ["ANTOM_MERCHANT_PRIVATE_KEY"]
ALIPAY_PUBLIC_KEY = os.environ["ANTOM_PUBLIC_KEY"]
CLIENT_ID = os.environ["ANTOM_CLIENT_ID"]
GATEWAY_HOST = os.environ["ANTOM_GATEWAY_URL"]
default_alipay_client = DefaultAlipayClient(GATEWAY_HOST, CLIENT_ID, MERCHANT_PRIVATE_KEY,
ALIPAY_PUBLIC_KEY)
alipay_pay_request = AlipayPayRequest()
alipay_pay_request.product_code = ProductCodeType.CASHIER_PAYMENT
alipay_pay_request.payment_notify_url = "https://www.yourNotifyUrl.com"
alipay_pay_request.payment_redirect_url = "https://www.yourRedirectUrl.com"
alipay_pay_request.payment_request_id = str(uuid.uuid4())
payment_method = PaymentMethod()
payment_method.payment_method_type = "GCASH"
alipay_pay_request.payment_method = payment_method
amount = Amount("PHP", "10000")
alipay_pay_request.payment_amount = amount
order = Order()
order.reference_order_id = "102775765675669"
order.order_description = "Mi Band 3 Wrist Strap Metal Screwless Stainless Steel For Xiaomi Mi Band 3"
order.order_amount = amount
goods_arr = []
good = Goods()
good.goods_brand = "goods_brand"
good.goods_name = "goods_name"
goods_arr.append(good)
order.goods = goods_arr
merchant = Merchant()
merchant.merchant_mcc = "merchantMcc"
merchant.reference_merchant_id = "referenceMerchantId"
order.merchant = merchant
alipay_pay_request.order = order
settlement_strategy = SettlementStrategy()
settlement_strategy.settlement_currency = "USD"
alipay_pay_request.settlement_strategy = settlement_strategy
env = Env()
env.terminal_type = TerminalType.APP
env.os_type = OsType.IOS
alipay_pay_request.env = env
# alipay_pay_request.is_authorization = "true"
print(alipay_pay_request.to_ams_json())
rsp_body = default_alipay_client.execute(alipay_pay_request)
alipay_pay_response = AlipayPayResponse(rsp_body)
if alipay_pay_response.result.result_status.name != ResultStatusType.F.name:
print(alipay_pay_response.payment_id)
print(alipay_pay_response.payment_create_time)
else:
print(alipay_pay_response.result.result_message)API Key access is not yet available to all merchants. Use this client only if API Key access has been enabled for your account; otherwise, use RSA.
Set ANTOM_GATEWAY_URL and ANTOM_API_KEY in your server environment.
This initializes the client; see the setup guide for a
complete sandbox request and its additional configuration.
import os
from com.alipay.ams.api.api_key_alipay_client import ApiKeyAlipayClient
client = ApiKeyAlipayClient(
os.environ["ANTOM_GATEWAY_URL"], os.environ["ANTOM_API_KEY"])Available in SDK version 1.7.0 and later.
Convert a decimal amount string into Antom's integer-string Amount.value,
convert it back to a fixed-precision decimal string, or validate an outbound
value. Conversion returns a string, not an Amount object, and uses bundled
currency rules without a network request.
Import the functions from the installed SDK:
from com.alipay.ams.api.tools.amount_util import from_amount, to_amount, validate
value = to_amount("10.25", "USD") # "1025"
amount = from_amount(value, "USD") # "10.25"
validate(value, "USD")validate returns None on success. Invalid input raises ValueError
(or TypeError for non-string input); bundled-rule loading failures raise RuntimeError.
Error messages include categories such as UNSUPPORTED_CURRENCY,
EXCESS_PRECISION, VALUE_TOO_LONG, and RULE_VIOLATION.
- Pass amounts, values, and currency codes as strings. Use uppercase currency codes and unsigned ASCII numbers, without spaces, separators, or exponents.
- Supported currencies: AUD, BDT, BRL, CAD, CLP, CNY, EUR, GBP, HKD, IDR, JPY, KRW, MXN, MYR, NZD, PEN, PHP, PKR, PLN, SGD, THB, TWD, USD, VND. Other codes are rejected; there is no default conversion multiplier.
- Conversion is exact and never rounds. Extra non-zero decimal places are rejected; trailing zero decimal places are allowed. Zero is accepted, but callers must check whether the target API permits a zero amount.
- The 16-digit limit applies to
Amount.value, not to the decimal input string or the business transaction limit. Conversion to a value checks the normalized result; conversion from a value and validation count all input digits, including leading zeros. - For IDR, conversion to a value and outbound validation require the value to be a multiple of 100. Conversion from a value does not apply this outbound restriction and never rounds the response amount.
See Antom's amount rules for the conversion convention. Supported payment-method currencies, transaction limits, and method-specific constraints (such as JKOPay TWD or Octopus HKD multiples) must be checked separately; this utility does not validate payment-method context.
Gateway responses with resultStatus S must be signed; responses with only one
of the signature and response-time headers are rejected.
Billing integrations: availableAmount now uses Amount; the AvailableAmount
model has been removed.
Install the optional HTTP/2 dependencies using the Python environment described in Installation.
python -m pip install --upgrade "global-open-sdk-python[http2]"meter/createSession uses the regular signed AMS transport. Use its session ID
to call meter/uploadEvent through execute_with_headers:
The fragment below assumes an initialized RSA client, a valid session ID from
meter/createSession, and a populated collection of meter event batches.
# Requires the http2 extra installed above.
from com.alipay.ams.api.request.billing.alipay_meter_upload_event_request import AlipayMeterUploadEventRequest
request = AlipayMeterUploadEventRequest()
request.meters = meters
response_body = default_alipay_client.execute_with_headers(
request, {"X-Session-Id": session_id}
)The SDK sends meter/uploadEvent to the gateway URL configured on the client,
without sandbox path rewriting, request signing, response signature verification,
or automatic retries. This API requires HTTP/2.
Use the exact transmitted path, timestamp, body, and configured keys. The variables below come from your request/response. Verify notifications before parsing their original body.
from com.alipay.ams.api.tools.signature_tool import sign, verify
signature = sign(http_method, path, client_id, request_time, request_body, merchant_private_key)
verified = verify(
http_method, path, client_id, response_time, response_body, response_signature, alipay_public_key
)For integration questions, contact overseas_support@service.alibaba.com.