All-In-One Checkout (V2)

端点目标 URL

沙盒环境请求地址：POST https://api.futurepay-develop.com/checkout/newSession

生产环境请求地址：POST https://api.futurepay.global/checkout/newSession

字段说明

调用的特定输入参数

字段名称	必填	类型	描述
`amount.currency`	M	string	消费者为您的商品或服务支付款项时所使用的货
`amount.value`	M	int	消费者为您的商品或服务实际支付的金额（ ISO 4217 标准）以自然数表示的 amount 值。默认情况下，此参数的值以最小货币单位为单位。例如，如果货币为 USD，金额为 1.00 USD，则此参数的值设置为 100;或者，如果货币为 JPY 且金额为 ¥1，则将此参数的值设置为 1。
`countryCode`	M	string	消费者所在国家的国际标准化组织（ISO）国家代码（如US代表美国，CN代表中国）。系统会根据该国家代码自动调整并显示在该国可用的支付方式，以确保消费者能够使用适合其所在国家的支付方式完成交易（ ISO 3166-1 标准）
`productDetail`	M	String	订单描述
`productName`	M	string	订单标题
`origin`	M	string	指订单来源，一般为网页地址（URL）
`reference`	M	string	由您的系统生成并分配给每笔订单的唯一标识符，用于再系统中追踪订单
`returnUrl`	M	string	指消费者在支付成功后，系统自动将消费者重定向到的网页地址（URL），此URL通常用于显示支付成功的确认页面，或将消费者带回到商户网站的指定页面
`enabledOneClick`	O	boolean	是否保存卡信息(目前仅支持International Cards )
`shopperReference`	O	string	用于是否保存卡信息，当保存卡信息的时候该字段必传，对应持卡人用户标识(目前仅支持International Cards )
`shopImgLink`	O	string	商品图片Url地址，需是可访问的（最大长度255）
`isexchange`	O	Boolean	是否开启换回，true：开启 false：关闭（默认开启）
`paymentMethod.type`	O	string	支付方式（设置此值后，收银台将优先选择传入的支付方式作为默认付款方式）
`paymentMethod.shopperEmail`	O	string	消费者邮箱地址
`paymentMethod.firstName`	O	string	消费者名字
`paymentMethod.lastName`	O	string	消费者姓氏
`paymentMethod.telephoneNumber`	O	string	付款人手机号，加纳、乌干达、肯尼亚、坦桑尼亚、喀麦隆=12位数字（包括区号），塞拉利昂=11位数字（包含区号），科特迪瓦=13位数字（包括区号），贝宁=13位数字（包含区号，格式为 229 01 ********，比如229 01 12345678）
`paymentMethod.statementDescriptor`	O	string	对账单描述符，详细见下文
`paymentMethod.captureMethod`	O	string	控制何时从客户账户中提取资金。可选值为：automatic（默认）、manual（授权付款）(目前仅支持International Cards ) https://doc.futurepay.global/update/docs/authorizationcapture#/
`directReturn`	O	Boolean	是否直接跳转returnUrl，True-直接跳转returnUrl
`webhookUrl`	O	string	订单结果回调通知地址
`browserInfo`	O	Object	设备浏览器信息（如不指定该信息，则会获取userAgent信息判断消费者终端信息）
├── `osType`	O	String	操作系统类型（如 IOS, ANDROID,OTHER）
├── `terminalType`	O	String	终端类型（如 APP, WAP,WEB,MINI_APP）

调用的特定响应参数

字段名	必填	类型	说明	示例值
`msg`	M	String	响应信息，表示请求的处理结果。	`success`
`code`	M	String	响应码，表示请求的处理状态，`0` 表示成功。更多code返回请参考该地址	`0`
`data`	M	Object	响应数据对象，包含具体的返回内容。	`{ "checkOutUrl": "https://checkout.futurepay-develop.com/checkout/createOrder?token=...","sessionToken":"44f0dce6-c49c-4cb6-9d17-3a86359d58e7"}`
└─ `checkOutUrl`	M	String	收银台跳转 URL，用于用户跳转到支付页面。	`https://checkout.futurepay-develop.com/checkout/createOrder?token=44f0dce6-c49c-4cb6-9d17-3a86359d58e7`
└─`sessionToken`	M	String	收银台会话Token	`44f0dce6-c49c-4cb6-9d17-3a86359d58e7`
`success`	M	Boolean	请求是否成功的标识。	`true`
`serverTime`	M	Long	服务器响应时间，Unix 时间戳（毫秒）。	`1727586009474`

集成

交易调用输入

{
    "amount": {
        "currency": "USD",
        "value": 100
    },
    "paymentMethod": {
        "type": "alipay",
        "firstName": "ming",
        "lastName": "xing",
        "shopperEmail": "[email protected]"
    },
    "productDetail": "购买产品详情/订单描述",
    "productName": "购买产品标题",
    "countryCode": "US",
    "origin": "fffmall.com",
    "reference": "24092905000017-564",
    "returnUrl": "https://wallet.futurepay-develop.com/api/PayNotify/paymentSynchronous/business_merchant_id/1/order_id/2083"
}

交易调用输出

{
    "msg": "success",
    "code": "0",
    "data": {
      "checkOutUrl": "https://checkout.futurepay-develop.com/checkout/createOrder?token=44f0dce6-c49c-4cb6-9d17-3a86359d58e7",
			"sessionToken":"44f0dce6-c49c-4cb6-9d17-3a86359d58e7"
    },
    "success": true,
    "serverTime": 1727586009474
}

WEBHOOK

{
    "appId": "1802583469172330496",
    "merchantId": "1802557498776006656",
    "notificationItems": [
        {
            "amount": {
                "currency": "USD",
                "value": 100
            },
            "eventCode": "TRANSACTION",
            "eventDate": 1727603276000,
            "merchantReference": "24092905000017-564",
            "paymentMethod": "skrill",
            "pspReference": "1840327561662562304",
            "resultCode": "SUCCEED"
        }
    ]
}

📘
请通过您的商户系统查看已激活的支付方式，以了解可用的支付选项。

对账单描述符

对账单描述符对银行对账单上的收款或付款进行解释。使用清晰准确的对账单描述符可以减少撤单和争议。银行和卡组织要求包含某些类型的信息，以帮助客户理解他们的对账单，对账单描述符的作用就是来提供这些信息。

客户发起付款成功之后，传送的paymentMethod.statementDescriptor参数将会出现在客户的对账单上。如果没有传送该参数，那么将会展示默认的静态对账单描述符，这个默认值需要您入网的时候提供给我们进行配置。

对于International Cards 支付方式，参数将会作为后缀，与默认的对账单描述符（前缀）、* 符号和空格连接在一起，形成客户看到的完整对账单描述符。

例如，配置的默认对账单描述符是Futurepay，传送的参数是Mall，那么完整对账单描述符是Futurepay* Mall。

格式要求：

仅包含拉丁字符。
完整的对账单描述符（静态+动态）包含 5 到 22 个字符，超过22字符将会被截取。
配置的默认对账描述符必须包含 2 到 10 个字符，其余字符留给动态后缀。
包含至少一个字母（如果使用前缀和后缀，两者都至少要有一个字母）。
不要包含以下任何特殊字符：<、>、\、'、"、*。
反映您的“经营名称”（DBA，即“Doing Business As”）。
包含多个常见术语或常见网站 URL。可以仅提供网站 URL，前提是它能在客户对账单上清晰准确地描述交易。