跳转至

礼品卡

购买礼品卡

HTTP请求

POST /v1/marketplace/sales/gift_cards

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "280a03fc-2255-11eb-adc1-0242ac120002",
    "sku": "NETFLI300",
    "currency": "MXN",
    "countryCode": "MX",
    "paymentType":"PAY_WITH_LINK",
    "allowPaymentMethods": [
        "BANK_TRANSFER_MX",
        "CREDIT_CARD"
    ],
    "targetPhoneNumber": "+5511999999999",
    "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":"280a03fc-2255-11eb-adc1-0242ac120002",
    "transactionId":"20200721-184332-824-3257-1404",
    "transactionStatus": "IN_PROGRESS",
    "transactionStatusCode": 200,
    "transactionErrorMsg": ""
}

HTTP Headers 字段说明

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

Request Body 字段说明

参数 是否必填 类型 描述
idempotencyKey String 此参数用于幂等目的，交易的唯一标识ID 长度不大于128个字节
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可能需要填写）
targetPhoneNumber String 手机号码（仅当支付类型为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 此次请求API状态代码，200代表API请求成功, 401 访问受限, 422 参数错误, 500 内部错误
errorMsg String 如果交易失败，返回的错误信息
idempotencyKey String 交易的幂等ID
transactionId String 此次交易的ID
transactionStatus String 此次交易的目前状态, 枚举值，SETTLED, IN_PROGRESS 或者 FAILED。
transactionStatusCode Integer 此次交易的状态码, 200表示交易成功或者进行中, 其他代表失败
transactionErrorMsg String 此次交易失败原因

礼品卡查询

通过幂等键查询礼品卡购买状态

请求

GET /v1/marketplace/sales/gift_cards/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": "NETFLI300",
    "price": "300",
    "priceInCents": "30000",
    "currency": "MXN",
    "createTime": "2021-07-26T20:41:53",
    "finalStatusTime": "2021-07-26 12:41:53 GMT+00:00",
    "activationCode": "AAABBNDS111EBEM",
    "activationMessage": "Activation Message"
}

HTTP Headers Details

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

Response Body Details

参数 类型 描述
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 礼品卡购买完成时间
activationCode String 礼品卡激活码
activationMessage String 礼品卡激活信息

查询可用礼品卡供应商

返回指定国家所有可用的礼品卡供应商

请求

GET /v1/marketplace/sales/gift_cards/{{countryCode}}/merchants

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

响应

Content-Type: application/json
{
    "statusCode":200,
    "errorMsg": "",
    "merchants": [
        {
            "merchantId": "Netflix",
            "merchantName": "Netflix",
            "iconUrl": "https://aws.s3.some.url/netflix.jpeg",
            "description": null
        },
        {
            "merchantId": "Spotify",
            "merchantName": "Spotify",
            "iconUrl": "https://aws.s3.some.url/Spotify.jpeg",
            "description": null
        },
        ......
    ]
}

HTTP Headers 字段说明

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

路径参数

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

Response Body 字段说明

参数 类型 描述
statusCode Integer 状态代码，200 代表成功2, 401 访问受限, 422 参数错误, 500 内部错误
errorMsg String 如果查询失败，返回的错误信息
merchants JSON Array 可用供应商列表

merchant Object 字段说明

参数 类型 描述
merchantId String 供应商ID
merchantName String 供应商名字
iconUrl String 供应商图标地址
description String 供应商描述

礼品卡Sku列表

请求

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

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

响应

Content-Type: application/json
{
    "statusCode":200,
    "errorMsg": "",
    "skus": [
        {
            "sku": "NETFLI150",
            "price": "150",
            "currency": "MXN",
            "merchantId": "Netflix",
            "description": "Netflix 150"
        },
        {
            "sku": "NETFLI300",
            "price": "300",
            "currency": "MXN",
            "merchantId": "Netflix",
            "description": "Netflix 300"
        },
        ......
    ]
}

HTTP Headers 字段说明

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

路径参数

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

Response Body 字段说明

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

sku Object 字段说明

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

获取指定礼品卡运营商的礼品卡套餐

请求

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

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

响应

Content-Type: application/json
{
    "statusCode":200,
    "errorMsg": "",
    "skus": [
        {
            "sku": "NETFLI150",
            "price": "150",
            "currency": "MXN",
            "merchantId": "Netflix",
            "description": "Netflix 150"
        },
        {
            "sku": "NETFLI300",
            "price": "300",
            "currency": "MXN",
            "merchantId": "Netflix",
            "description": "Netflix 300"
        },
        ......
    ]
}

HTTP Headers 字段说明

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

路径参数

参数 是否必填 类型 描述
countryCode String 用户的国际缩写码，遵循ISO 3166-1 alpha-2 code标准, 长度2个字节, 例如 BR, MX
merchantId String 礼品卡运营商ID

Response Body 字段说明

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

sku Object 字段说明

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