亮色模式

API - 支付

POST/v3/merchants/<merchant_id>/payments

:::tip[]

签名构建因子是入参列表中所有参数；
访问时需要将替换为商户号；
:::

环境域名地址

生产环境：https://gpapi.lianlianpay.com/v3/merchants/<merchant_id>/payments
沙箱环境：https://celer-api.LianLianpay-inc.com/v3/merchants/<merchant_id>/payments

接口协议结构体

详情可查看请求与响应结构

请求参数

Header 参数

signature

string

签名

必需

示例值:

XJqQTCs1QTsp+xO3iWrEMhMZUF9Wt+s2XTilT48lyv3zCmJS1+twA9cYsq9Bg9hfTnOFziCaU0OD3ddYWTMRf13uyLjwwOKD6LWyBCd+17Fq4bBdFcCwiuA6ZUkXbIWKiLACf8gY0JkKpuEvXSSrvHcpS9MPakuXKKwOBRY1UXBhWr2bL3qr8r4bLUk1A3 5ZU7Oj5r2xZV3JrdeFYqBLss1jbXNT9bS4J5JFoFKw/xBzoBkYh7btm28b8i8Q5lY2Vu7vZVK+BGKfBff2PQOJ347VGyR3+ch4qrw0ABRC52jEycWWoGQbnzs6W8DwBGg64/aR7GpNz9sHIy6YW8KwZg==

timezone

string

时区

必需

示例值:

Asia/Hong_Kong

timestamp

string

必需

格式化时间戳，格式为：yyyyMMddHHmmss

示例值:

20211022160000

Content-Type

string

必需

示例值:

application/json

merchant_transaction_id

string

商户支付交易ID

必需

由商家自定义，保证在商户端唯一

<= 64 字符

示例值:

20200808000000008

merchant_id

string

商户号

必需

由连连全球收单创建分配

<= 32 字符

示例值:

202103310000001001

sub_merchant_id

string

站点号

必需

由连连全球收单创建分配

<= 32 字符

示例值:

202103313321536404

notification_url

string

支付结果通知地址

必需

用于商家服务端接收支付结果通知的地址

<= 512 字符

示例值:

https://acquiring.lianlianpay.com/notification

redirect_url

string

成功回跳地址

必需

支付成功后，用户跳转到支付成功地址，默认POST请求，注意此参数中不允许出现“#”符号

<= 512 字符

示例值:

https://acquiring.lianlianpay.com/redirect

cancel_url

string

支付取消地址

可选

收银台模式必传，用户在收银台取消支付后，跳转到取消地址

<= 512 字符

示例值:

https://acquiring.lianlianpay.com/cancel

country

string

商户主体国家编码

必需

详情可查看国家编码

<= 2 字符

示例值:

payment_method

string

支付方式

可选

Direct API与iframe模式必传，详情可查看支付方式，当收银台模式传入该参数，收银台则指定展示该支付方式，默认不传展示全部

<= 32 字符

示例值:

inter_credit_card

additional_info

string

补充信息

可选

Direct API模式必传
传递referers地址，json对象字符化

<= 1024 字符

示例值:

{"site_url":"https://www.antoinetton.com"}

merchant_order

object

商户订单信息

必需

merchant_order_id

string

商户订单号

必需

由商家自定义

<= 64 字符

示例值:

20200808000888888

merchant_user_no

string

商户的用户ID

可选

由商家自定义，使用保存卡功能必传

<= 64 字符

示例值:

100036

merchant_order_time

string

商户订单时间

必需

格式为：yyyyMMddHHmmss

<= 14 字符

示例值:

20221231135923

order_description

string

订单描述

可选

在收银台页面订单信息中显示

<= 256 字符

示例值:

测试订单

order_amount

number

订单金额

必需

单位精确到小数点后两位，金额必须大于0

>= 0.1

示例值:

88.88

order_currency_code

string

订单币种

必需

详情可查看币种

<= 3 字符

示例值:

USD

products

array[object (PRODUCT) {9}]

商品详情列表

必需

总长度不能超过40960

shipping

object

收货人信息

可选

收货人信息，商品为实物必传

customer

object (CUSTOMER)

客户详情

可选

支付方式为国际卡，且Direct API与iframe模式必传，收银台模式选传；
支付方式为本地支付时，建议填写，有助于提高交易成功率；

customer_type

enum<string>

付款人身份类型

必需

个人 I =Individual
公司 C=Corporation

<= 1 字符

枚举值:

first_name

string

付款人名

可选

当 customer_type = “I” 时必传

<= 64 字符

示例值:

San

last_name

string

付款人姓

可选

当 customer_type = “I” 时必传

<= 64 字符

示例值:

Zhang

full_name

string

付款人名称

必需

个人格式为：first_name+空格+last_name，公司填写公司名称

<= 128 字符

示例值:

Zhang San

gender

enum<string>

性别

可选

男性：male；女性：female；未知的：undefined；

<= 16 字符

枚举值:

malefemaleundefined

id_type

enum<string>

付款人证件类型

可选

支付方式为pix，boleto时必传

<= 16 字符

枚举值:

CPFCNPJ

id_no

string

付款人证件号

可选

<= 32 字符

示例值:

110102199503312837

string

付款人邮箱地址

可选

邮箱和手机号至少传一个

<= 64 字符

示例值:

zhangsan@gmail.com

phone

string

付款人手机号

可选

邮箱和手机号至少传一个

<= 32 字符

示例值:

+8618600000000

company

string

付款人所在公司名称

可选

<= 128 字符

open_id

string

第三方平台客户标识

可选

支付方式为微信小程序支付时必传

<= 128 字符

address

object (ADDRESS)

付款地址信息

可选

美国地区必传

payment_data

object

支付信息

可选

支付方式为国际卡，且Direct API与iframe模式必传

card

object

银行卡信息

可选

Direct API与Iframe模式必传

installments

number

本地卡分期期数

可选

默认不分期，则传“1”

<= 99

默认值:

payment_mode

string

模式

可选

信用卡订阅参数必须传入，订阅模式传入：subscription

subscription_info

object

信用卡订阅支付参数

可选

terminal_data

object (TERMINALDATA)

用户终端信息

可选

Direct API模式必传

user_order_ip

string

用户下单IP

可选

Direct API模式必填

<= 64 字符

user_client_mode

enum<string>

客户端类型

可选

本地支付方式，且Direct API与iframe模式必传

<= 8 字符

枚举值:

10131621

user_client_app_type

enum<string>

操作系统

可选

本地支付方式，且Direct API与iframe模式必传
当客户端类型为APP时必传

<= 2 字符

枚举值:

user_client_android_imei

string

IMEI

可选

<= 64 字符

user_client_android_sim_id

string

SIM ID

可选

<= 64 字符

user_client_ios_machine_id

string

UUID

可选

<= 128 字符

user_client_browser_accept_header

string

浏览器请求头

可选

支付方式为国际卡，且Direct API模式必传

<= 256 字符

user_client_browser_color_depth

number

浏览器颜色/深浅

可选

支付方式为国际卡，且Direct API模式必传

<= 999

user_client_browser_java_enabled

boolean

浏览器是否支持java

可选

支付方式为国际卡，且Direct API模式必传

user_client_browser_js_enabled

boolean

浏览器是否可以执行JS

可选

不传默认为true

user_client_browser_language

string

浏览器语言

可选

支付方式为国际卡，且Direct API模式必传

<= 8 字符

user_client_browser_screen_height

number

浏览器屏幕高度

可选

支付方式为国际卡，且Direct API模式必传

<= 99999

user_client_browser_screen_width

number

浏览器屏幕宽度

可选

支付方式为国际卡，且Direct API模式必传

<= 99999

user_client_browser_time_zone_offset

string

浏览器时区

可选

支付方式为国际卡，且Direct API模式必传，浏览器本地时间与协调世界时（UTC）之间的时间差，以分钟为单位计算，例如：UTC+8 的北京时间 → -480 （8小时 × 60分钟），UTC-5 的纽约时间 → +300 （5小时 × 60分钟）

<= 48 字符

user_client_browser_user_agent

string

浏览器用户代理

可选

支付方式为国际卡，且Direct API模式必传

<= 256 字符

{
  "merchant_transaction_id": "20200808000000008",
  "merchant_id": "202103310000001001",
  "sub_merchant_id": "202103313321536404",
  "notification_url": "https://acquiring.lianlianpay.com/notification",
  "redirect_url": "https://acquiring.lianlianpay.com/redirect",
  "cancel_url": "https://acquiring.lianlianpay.com/cancel",
  "country": "US",
  "payment_method": "nostrud magna dolor",
  "additional_info": "{\"site_url\":\"https://www.antoinetton.com\"}",
  "merchant_order": {
    "merchant_order_id": "20200808000888888",
    "merchant_user_no": "100036",
    "merchant_order_time": "20221231135923",
    "order_description": "测试订单",
    "order_amount": null,
    "order_currency_code": "USD",
    "products": [
      {
        "product_id": "50306",
        "name": "测试商品",
        "description": "测试商品描述",
        "price": null,
        "quantity": null,
        "category": "36321643",
        "sku": "775A3TM4",
        "url": "https://acquiring.lianlianpay.com/xxx.jpg",
        "shipping_provider": "other"
      },
      {
        "product_id": "50306",
        "name": "测试商品",
        "description": "测试商品描述",
        "price": null,
        "quantity": null,
        "category": "36321643",
        "sku": "775A3TM4",
        "url": "https://acquiring.lianlianpay.com/xxx.jpg",
        "shipping_provider": "other"
      }
    ],
    "shipping": {
      "first_name": "san",
      "last_name": "Zhang",
      "name": "Zhang san",
      "phone": "+8618600000000",
      "cycle": "24h",
      "address": {
        "line1": "美国纽约市XXXX",
        "line2": "美国纽约市XXXX",
        "country": "US",
        "city": "NY",
        "state": "UT",
        "postal_code": "10001",
        "district": "Alagoas"
      }
    }
  },
  "customer": {
    "customer_type": "I",
    "first_name": "san",
    "last_name": "Zhang",
    "full_name": "Zhang san",
    "gender": "male",
    "id_type": "CPF",
    "id_no": "110102199503312837",
    "email": "zhangsan@gmail.com",
    "phone": "+8618600000000",
    "company": "sint nostrud",
    "open_id": "27",
    "address": {
      "line1": "美国纽约市XXXX",
      "line2": "美国纽约市XXXX",
      "country": "US",
      "city": "NY",
      "state": "UT",
      "postal_code": "10001",
      "district": "Alagoas"
    }
  },
  "payment_data": {
    "card": {
      "holder_name": "Zhang san",
      "id_type": "CPF",
      "id_no": "1234567890",
      "card_no": "4200000000000000",
      "card_type": "C",
      "bank_code": "214",
      "card_brand": "visa",
      "card_expiration_year": "30",
      "card_expiration_month": "12",
      "cvv": null,
      "phone_number": "+8618600000000",
      "email": "zhangsan@gmail.com",
      "card_token": "越野车",
      "billing_address": {
        "line1": "美国纽约市XXXX",
        "line2": "美国纽约市XXXX",
        "country": "US",
        "city": "NY",
        "state": "UT",
        "postal_code": "10001",
        "district": "Alagoas"
      }
    },
    "installments": null
  },
  "terminal_data": {
    "user_order_ip": "",
    "user_client_mode": "",
    "user_client_app_type": "",
    "user_client_android_imei": "",
    "user_client_android_sim_id": "",
    "user_client_ios_machine_id": "",
    "user_client_browser_accept_header": "",
    "user_client_browser_color_depth": null,
    "user_client_browser_java_enabled": true,
    "user_client_browser_js_enabled": true,
    "user_client_browser_language": "",
    "user_client_browser_screen_height": null,
    "user_client_browser_screen_width": null,
    "user_client_browser_time_zone_offset": "",
    "user_client_browser_user_agent": ""
  }
}

示例代码

返回响应

成功(200)

HTTP 状态码: 200

内容格式: JSONapplication/json

return_code

string

返回码

必需

返回码

return_message

string

返回消息

必需

返回消息

trace_id

string

追踪号

必需

需要技术支持时候，请提供至LianLian Pay技术人员

decline_code

string

业务拒绝详情code

必需

业务错误码

order

object

支付数据

必需

支付提交成功才有返回值

ll_transaction_id

string

连连支付订单号

必需

<= 32 字符

merchant_transaction_id

string

商户支付交易ID

必需

<= 64 字符

payment_url

string

支付跳转url

可选

用户需要跳转此地址完成支付，当3ds_status= challenge时，存放的为3DS 安全认证url

<= 2048 字符

3ds_status

string

3ds认证

可选

CHALLENGE：需要3ds认证；
空值：不需要3ds认证

<= 10 字符

qrcode

string

二维码地址

可选

<= 512 字符

payment_data

object (PAYMENTRESPONSEPAYMENTDATA)

支付数据

必需

ext_info

string

扩展字段

必需

扩展参数，json 格式字符串，SDK支付所需参数名称sdk_data

{
    "return_code": "SUCCESS",
    "return_message": "Success",
    "trace_id": "14831.109.16406762306420461",
    "order": {
        "ll_transaction_id": "202112280336075",
        "merchant_transaction_id": "202112281523270200",
        "payment_data": {
            "payment_currency_code": "USD",
            "payment_amount": "1.00",
            "exchange_rate": "1.00000000",
            "payment_time": "20211228152354",
            "payment_status": "PS",
            "settlement_currency_code": "USD",
            "settlement_amount": "1.00",
            "account_date": "20211228"
        },
        "payment_url": "https://celer-gateway.lianlianpay-inc.com/publish/f654db4c584547149c41951cfe122ec7"
    }
}

// 以上例子返回了一个支付成功结果，可以看到 payment_status 为 PS，也就是支付成功，此种请求为同步返回，商户可直接更新自己对应的订单，更多的支付返回结果为中间状态也就是 PP，此种结果为等待异步通知支付的结果；