跳转至

手机充值

手机充值

发起充值

对预付费手机进行充值

HTTP请求

POST /v1/marketplace/sales/topups

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "280a03fc-2255-11eb-adc1-0242ac120002",
    "targetPhoneNumber": "+5511234567890",
    "sku": "TAE010",
    "currency": "MXN",
    "countryCode": "MX",
    "paymentType":"PAY_WITH_LINK",
    "allowPaymentMethods": [
        "BANK_TRANSFER_MX",
        "CREDIT_CARD"
    ],
    "email": "liquido-test@gmail.com",
    "billingAddress": {
        "zipCode": "04849333",
        "state": "SP",
        "city": "sao paulo",
        "district": "Jardim Gaivotas",
        "street": "Rua 9 de setembro",
        "number": "15",
        "complement": "casa",
        "country": "MX"
    },
    "callbackUrl": "https://your-domain/callback/",
    "redirectUrl": "https://your-domain/checkout-page"
}
Content-Type: application/json
{
    "statusCode": 200,
    "errorMsg": "",
    "idempotencyKey": "7e18e719-0000-0716-a92a-2b4faeb70008",
    "transactionId": "20210715-175206-145-0369-0449",
    "transactionStatus": "SETTLED",
    "transactionStatusCode": 200,
    "transactionErrorMsg": ""
}

HTTP Headers 字段说明

Key Value
Content-Type application/json
x-api-key {{api_key}}

Request Body 字段说明

参数 是否必填 类型 描述
idempotencyKey String 此参数用于幂等目的，交易的唯一标识ID 长度不大于128个字节
targetPhoneNumber String 充值手机号码。必须包含国际区号，如"+55".
sku String 充值套餐的SKU
currency String 货币代码，长度为3个字节，例如BRL、MXN
countryCode String 国家代码，长度为2个字节，例如BR、MX，不填默认MX
paymentType String 支付类型，枚举值：PREPAID、PAY_WITH_LINK，不填默认PREPAID
allowPaymentMethods String 声明支付页面包含哪些支付方式。 不填默认值是CREDIT_CARD.（仅当支付类型为PAY_WITH_LINK可能需要填写）
email String 邮箱（仅当支付类型为PAY_WITH_LINK可能需要填写）
billingAddress String 账单地址。如果商户在支付流程之前预收集了用户的账单地址，可以在创建payment link时发送给liquido。该信息可用于Boleto支付表单的预填充。（仅当支付类型为PAY_WITH_LINK可能需要填写）
callbackUrl String 当支付状态变化时，liquido会向callbackUrl发送一个post请求。
redirectUrl String 当redirectUrl非空时，payment link支付成功后会重定向到redirectUrl。（仅当支付类型为PAY_WITH_LINK可能需要填写）

AllowPaymentMethods 对象字段说明

支付方式 国家代码 限制
CREDIT_CARD BR, MX, CO
PIX BR
BOLETO BR >= 5BRL
BANK_TRANSFER_BR BR
BANK_TRANSFER_MX MX
PAY_CASH MX, CO <= 20,000 MXN or <= 3,000,000 COP
PSE CO >= 1500COP
NEQUI CO >= 1500COP

BillingAddress 对象字段说明

参数 必填 类型 描述
zipCode String 邮政编码，如巴西的CEP
state String 州，缩写，如圣保罗是SP
city String 城市.
district String 区县.
street String 街道.
number String 门牌号.
complement String 补充信息.
country String 国家代码.

Response Body 字段说明

参数 类型 描述
statusCode Integer 状态代码，200 代表成功, 401 访问受限, 422 参数错误, 500 内部错误
errorMsg String 如果交易失败，返回的错误信息
idempotencyKey String 交易的幂等键
transactionId String 此次交易的ID
transactionStatus String 此次交易的目前状态, 枚举值，SETTLED, IN_PROGRESS 或者 FAILED。
transactionStatusCode Integer 此次交易的状态码, 200表示交易成功或者进行中, 其他代表失败
transactionErrorMsg String 此次交易失败原因

手机充值查询

通过幂等ID查询手机充值状态

请求

GET /v1/marketplace/sales/topups/key/{{idempotencyKey}}

Request Headers
{
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

响应

Content-Type: application/json
{
    "statusCode": 200,
    "errorMsg": "",
    "idempotencyKey":"280a03fc-2255-11eb-adc1-0242ac120001",
    "transactionId":"09461d96-2252-11eb-adc1-0242ac120002",
    "transactionStatus":"SETTLED",
    "transactionStatusCode": 200,
    "transactionErrorMsg": "",
    "sku": "TAE010",
    "price": "10",
    "priceInCents": "1000",
    "currency": "MXN",
    "createTime": "2021-07-26T20:41:53",
    "finalStatusTime": "2021-07-26 12:41:53 GMT+00:00",
    "phoneNumber": "5581124237"
}

HTTP Headers 字段说明

Key Value
x-api-key {{api_key}}
Content-Type application/json

路径参数

参数 是否必填 类型 描述
idempotencyKey String 交易的幂等ID

Response Body 字段说明

参数 类型 描述
statusCode Integer 此次请求API状态代码，200代表API请求成功, 401 访问受限, 422 参数错误, 500 内部错误
errorMsg String 如果API请求失败，返回的错误信息
idempotencyKey String 幂等ID，交易的唯一标识ID
transactionId String 交易ID，系统未成功发给运营商充值前，这个值有可能为空
transactionStatus String 此次交易的状态，枚举值，"SETTLED", "FAILED", "IN_PROGRESS"
transactionStatusCode Integer 此次交易的状态码, 200表示交易成功或者进行中, 其他代表失败
transactionErrorMsg String 此次交易失败原因
sku String 充值套餐SKU
price String 充值金额
priceInCents Long 充值金额，单位是货币最小粒度。如 1 = 0.01BRL
currency String 充值货币代码，例如巴西的BRL
createTime Time 手机充值请求时间
finalStatusTime Time 手机充值完成时间
phoneNumber Time 充值的手机号码

查询充值运营商

返回当前国家所有可用的充值运营商

请求

GET /v1/marketplace/sales/topups/{{country}}/merchants

Request Headers
{
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

响应

Content-Type: application/json
{
    "statusCode":200,
    "errorMsg": "",
    "merchants": [
        {
            "merchantId": "TA",
            "merchantName": "Telcel",
            "iconUrl": "https://s3.some.url/Telcel.jpeg",
            "description": "Telcel Tiempo Aire"
        },
        {
            "operatorId": "MOV",
            "operatorName": "Movistar",
            "iconUrl": "https://s3.some.url/Movistar.jpeg",
            "description": "Movistar Tiempo Aire"
        }
    ]
}

HTTP Headers 字段说明

Key Value
x-api-key {{api_key}}
Content-Type application/json

路径参数

参数 类型 描述
countryCode String 用户的国家缩写码，遵循ISO 3166-1 alpha-2 code标准, 长度2个字节, 例如 BR, MX

查询参数

参数 是否必填 类型 描述
phoneNumber String 充值手机号码，countryCode为BR时必填。必须包含国际区号，如"+55".

Response Body 字段说明

参数 类型 描述
statusCode Integer 状态代码，200 代表成功, 401 访问受限, 422 参数错误, 500 内部错误
errorMsg String 如果查询失败，返回的错误信息
merchants JSON Array 可用运营商列表
JSON字段 类型 描述
merchantId String 运营商ID
merchantName String 运营商名字
iconUrl String 运营商图标地址
description String 运营商描述

获取可用的充值套餐

获取当前可用的充值套餐列表

请求

GET /v1/marketplace/sales/topups/{{countryCode}}}/skus

Request Headers
{
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

响应

Content-Type: application/json
{
    "statusCode":200,
    "errorMsg": "",
    "skus": [
        {
            "name": "UNE020",
            "description": "Unefon Tiempo Aire 015",
            "price": "20",
            "currency": "MXN",
            "merchantId": "Unefon"
        },
        {
            "name": "UNE020",
            "description": "Unefon Tiempo Aire 020",
            "price": "20",
            "currency": "MXN",
            "merchantId": "Unefon"
        }
    ]
}

HTTP Headers 字段说明

Key Value
x-api-key {{api_key}}
Content-Type application/json

路径参数

参数 类型 描述
countryCode String 用户的国家缩写码，遵循ISO 3166-1 alpha-2 code标准, 长度2个字节, 例如 BR, MX

查询参数

参数 是否必填 类型 描述
phoneNumber String 充值手机号码，countryCode为BR时必填。必须包含国际区号，如"+55".

Response Body 字段说明

参数 类型 描述
statusCode Integer 状态代码，200 代表成功, 401 访问受限, 422 参数错误, 500 内部错误
errorMsg String 如果查询失败，返回的错误信息
skus JSON Array 充值套餐列表

sku Object 字段说明

参数 类型 描述
name String 充值套餐SKU
description String 充值套餐描述
price String 充值金额，单位是货币最小粒度。如 1 = 0.01BRL
currency String 充值货币代码
merchantId String 充值运营商ID

获取指定手机充值运营商当前可用的充值套餐

请求

GET /v1/marketplace/sales/topups/{{countryCode}}}/{{merchantId}}}/skus

Request Headers
{
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

响应

Content-Type: application/json
{
    "statusCode":200,
    "errorMsg": "",
    "skus": [
        {
            "name": "UNE050",
            "description": "Unefon Tiempo Aire 050",
            "price": "50",
            "currency": "MXN",
            "merchantId": "Unefon"
        },
        {
            "name": "UNE070",
            "description": "Unefon Tiempo Aire 070",
            "price": "70",
            "currency": "MXN",
            "merchantId": "Unefon"
        }
    ]
}

HTTP Headers 字段说明

Key Value
x-api-key {{api_key}}
Content-Type application/json

路径参数

参数 类型 描述
countryCode String 用户的国家缩写码，遵循ISO 3166-1 alpha-2 code标准, 长度2个字节, 例如 BR, MX
merchantId String 手机充值运营商ID

查询参数

参数 是否必填 类型 描述
phoneNumber String 充值手机号码，countryCode为BR时必填。必须包含国际区号，如"+55".

Response Body 字段说明

参数 类型 描述
statusCode Integer 状态代码，200 代表成功, 401 访问受限, 422 参数错误, 500 内部错误
errorMsg String 如果查询失败，返回的错误信息
skus JSON Array 充值套餐列表

sku Object 字段说明

参数 类型 描述
name String 充值套餐SKU
description String 充值套餐描述
price String 充值金额，单位是货币最小粒度。如 1 = 0.01BRL
currency String 充值货币代码
merchantId String 充值运营商ID
回到页面顶部