跳转至

PIX

PIX是巴西一种新的支付方式，由当地中央银行正式推出，可实现支付即时确认和全天候使用。用户可以使用任意一家开户银行或电子钱包App，通过扫描二维码的方式完成支付

HTTP请求

POST /v1/payments/charges/pix

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

使用DIRECT交易流程创建一个PIX支付

Request Body
{
    "idempotencyKey": "hz-testpixdynamic-230703-001",
    "amount": 100,
    "currency": "USD",
    "country": "BR",
    "paymentMethod": "PIX_DYNAMIC_QR",
    "paymentFlow": "DIRECT",
    "payer": {
        "name": "Thiago Gabriel",
        "email": "thiago@example.com",
        "document": {
            "documentId": "53033315550",
            "type": "CPF"
        },
        "phone": "+55 5058149876",
        "billingAddress": {  
            "zipCode": "04849333",
            "state": "SP",
            "city": "sao paulo",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "country": "BR"
        }
    },
    "orderInfo": {  
        "orderId": "test-order-id",  
        "shippingInfo": { 
            "name": "shipping test name",  
            "phone": "+55 5058149876",  
            "email": "thiago@example.com",
            "address": {  
                "zipCode": "04849333",
                "state": "SP",
                "city": "sao paulo",
                "district": "Jardim Gaivotas",
                "street": "Rua 9 de setembro",
                "number": "15",
                "complement": "casa",
                "country": "BR"
            }
        }
    },
    "expirationInfo": {
        "expiresAt": 1688396709
    },
    "callbackUrl": "",
    "description": "hello world",
    "subMerchantId": "UUID"
}

使用REDIRECT交易流程创建一个PIX支付

Request Body
{
    "idempotencyKey": "hz-testpixdynamic-230703-001",
    "amount": 100,
    "currency": "USD",
    "country": "BR",
    "paymentMethod": "PIX_DYNAMIC_QR",
    "paymentFlow": "REDIRECT",
    "payer": {
        "name": "Thiago Gabriel",
        "email": "thiago@example.com",
        "document": {
            "documentId": "53033315550",
            "type": "CPF"
        },
        "phone": "+55 5058149876",
        "billingAddress": {  
            "zipCode": "04849333",
            "state": "SP",
            "city": "sao paulo",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "country": "BR"
        }
    },
    "orderInfo": {  
        "orderId": "test-order-id",  
        "shippingInfo": { 
            "name": "shipping test name",  
            "phone": "+55 5058149876",  
            "email": "thiago@example.com",
            "address": {  
                "zipCode": "04849333",
                "state": "SP",
                "city": "sao paulo",
                "district": "Jardim Gaivotas",
                "street": "Rua 9 de setembro",
                "number": "15",
                "complement": "casa",
                "country": "BR"
            }
        }
    },
    "expirationInfo": {
        "expiresAt": 1688396709
    },
    "callbackUrl": "",
    "description": "hello world",
    "subMerchantId": "UUID",
    "merchantRedirectInfo": {
        "merchantPageUrl": "https://www.merchantpageexample.com/123456"
    }
}
Content-Type: application/json
{
    "transferStatusCode": 200,
    "idempotencyKey": "hz-testpixdynamic-230703-001",
    "referenceId": "hz-testpixdynamic-230703-001",
    "paymentFlow": "REDIRECT",
    "paymentMethod": "PIX_DYNAMIC_QR",
    "amount": 100,
    "currency": "USD",
    "finalAmount": 550,
    "finalCurrency": "BRL",
    "country": "BR",
    "createTime": "2023-07-03 09:32:32 UTC",
    "scheduledTime": "2023-07-03 09:59:46 UTC",
    "payer": {
        "name": "Thiago Gabriel",
        "document": {
            "documentId": "53033315550",
            "type": "CPF"
        },
        "email": "thiago@example.com",
        "phone": "+55 81987654321",
        "billingAddress": {
            "br": true,
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "district": "Jardim Gaivotas",
            "city": "sao paulo",
            "state": "SP",
            "zipCode": "04849333",
            "country": "BR"
        }
    },
    "transferStatus": "IN_PROGRESS",
    "description": "hello world",
    "callbackUrl": "",
    "transferDetails": {
        "pix": {
            "qrCode": "00020126890014BR.GOV.BCB.PIX2567api-pix.bancobs2.com.br/spi/v2/61ee4152-b3a2-435f-945f-ac52a268f2c552040000530398654045.505802BR5925LIQUIDO BRL PAGAMENTOS DI6014Belo Horizonte61083038040362070503***63045CE7",
            "qrCodeType": "DYNAMIC",
            "expirationTime": "2023-07-03 15:05:09 UTC"
        }
    },
    "amountDetails": {
        "taxAmountDetails": [
            {
                "taxRate": {
                    "modifierType": "RATE",
                    "rate": 0.0038,
                    "type": "BR_IOF_FX_TAX"
                },
                "amount": 2
            }
        ],
        "fxAmountDetails": {
            "fxRate": {
                "modifierType": "RATE",
                "base": "USD",
                "target": "BRL",
                "timestamp": 1664443743,
                "exchangeRate": 5.48350980
            },
            "baseAmount": 100,
            "targetAmount": 548
        }
    },
    "subMerchantId": "UUID",
    "redirectUrl": "https://www.redirect-qa.liquido.com?uid=97d6483b-78f5-43e6-8efc-5ef415b7a33f",
    "merchantRedirectInfo": {
        "merchantPageUrl": "https://www.merchantpageexample.com/123456"
    }
}

通知 / 回调

Content-Type: application/json
{
    "eventType": "CHARGE_SUCCEEDED",
    "data":  {
        "chargeDetails": {
            "transferStatusCode": 200,
            "idempotencyKey": "hz-testpixdynamic-230703-001",
            "referenceId": "hz-testpixdynamic-230703-001",
            "paymentFlow": "REDIRECT",
            "paymentMethod": "PIX_DYNAMIC_QR",
            "amount": 100,
            "currency": "USD",
            "finalAmount": 550,
            "finalCurrency": "BRL",
            "country": "BR",
            "createTime": "2023-07-03 09:32:32 UTC",
            "scheduledTime": "2023-07-03 09:59:46 UTC",
            "finalStatusTime": "2023-07-03 09:59:46 UTC",
            "payer": {
                "name": "Thiago Gabriel",
                "document": {
                    "documentId": "53033315550",
                    "type": "CPF"
                },
                "email": "thiago@example.com",
                "phone": "+55 81987654321",
                "billingAddress": {
                    "br": true,
                    "street": "Rua 9 de setembro",
                    "number": "15",
                    "complement": "casa",
                    "district": "Jardim Gaivotas",
                    "city": "sao paulo",
                    "state": "SP",
                    "zipCode": "04849333",
                    "country": "BR"
                }
            },
            "transferStatus": "IN_PROGRESS",
            "description": "hello world",
            "callbackUrl": "",
            "transferDetails": {
                "pix": {
                    "qrCode": "00020126890014BR.GOV.BCB.PIX2567api-pix.bancobs2.com.br/spi/v2/61ee4152-b3a2-435f-945f-ac52a268f2c552040000530398654045.505802BR5925LIQUIDO BRL PAGAMENTOS DI6014Belo Horizonte61083038040362070503***63045CE7",
                    "qrCodeType": "DYNAMIC",
                    "expirationTime": "2023-07-03 15:05:09 UTC"
                }
            },
            "amountDetails": {
                "taxAmountDetails": [
                    {
                        "taxRate": {
                            "modifierType": "RATE",
                            "rate": 0.0038,
                            "type": "BR_IOF_FX_TAX"
                        },
                        "amount": 2
                    }
                ],
                "fxAmountDetails": {
                    "fxRate": {
                        "modifierType": "RATE",
                        "base": "USD",
                        "target": "BRL",
                        "timestamp": 1664443743,
                        "exchangeRate": 5.48350980
                    },
                    "baseAmount": 100,
                    "targetAmount": 548
                }
            },
            "subMerchantId": "UUID",
            "redirectUrl": "https://www.redirect-qa.liquido.com?uid=97d6483b-78f5-43e6-8efc-5ef415b7a33f",
            "merchantRedirectInfo": {
                "merchantPageUrl": "https://www.merchantpageexample.com/123456"
            }
        }
    }
}

Request Headers 字段说明

Key Value
Authorization "bearer" + " " + {{access_token}}
x-api-key {{api_key}}

Request Body 字段说明

参数 必填 类型 描述
idempotencyKey String 商户系统创建的唯一ID， 长度不大于128个字节。
amount Long 收款金额，单位是货币最小粒度。如 1 = 0.01BRL
country String 国家编号国际缩写码，遵循ISO 3166-1 alpha-2 code标准, 如巴西BR
currency String 货币代码，如巴西BRL
paymentMethod String 交易方式，枚举，如PIX_DYNAMIC_QR
paymentFlow String 交易流程, 如DIRECT 或 REDIRECT
payer JSON 买家个人信息。
expirationInfo JSON pix支付过期时间。 过期时间应当比当前时间大于3600秒,小于604800秒(7天)。 如果想要开通长期有效的PIX二维码，请联系我们的售前人员。
orderInfo JSON 订单信息
description String 描述。
注意：
1. 描述的最大长度是25个字符。
callbackUrl String 接收交易状态变更通知的地址。接收post请求。
subMerchantId String 子商户ID。商户类型为PSP时必填。
merchantRedirectInfo JSON 重定向回商户页面的信息。
riskData JSON 支付的风险信息。MERCHANT_APP_NAME 或 MERCHANT_WEBSITE 在riskData中必须填一个。 请参考这里查看更多详情。

创建一个带风控信息的支付

请参考这里查看更多详情。

Payer 对象字段说明

参数 必填 类型 描述
name String 名字，全称（入参名字规范：只允许大小写字母，数字和空格的组合。请勿包含西班牙语和葡萄牙语字母，以及其他特殊字符。）
email String 邮箱。
phone String 电话号码，需包含“+55”的前缀。
document JSON 可确认身份的证件，例如巴西居民的CPF.
billingAddress JSON 账单邮寄地址.

document 对象字段说明

参数 必填 类型 描述
documentId String 证件号码
type String 证件类型，暂时支持CPF或者CNPJ

billingAddress 对象字段说明

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

orderInfo 对象字段说明

参数 必填 类型 描述
orderId String 订单号
shippingInfo JSON 运输信息

shippingInfo 对象字段说明

参数 必填 类型 描述
name String 名称
phone String 电话号码，需包含“+55”的前缀。
email String 邮箱地址
address JSON 地址信息，结构和billingAddress一致

expirationInfo 对象字段说明

参数 必填 类型 描述
expiresAt Long pix支付过期时间，秒级时间戳，如: 1651035000. 应大于当前时间3600s到604800s

merchantRedirectInfo 对象字段说明

参数 必填 类型 描述
merchantPageUrl String 此URL是重定向回商户页面的URL。当您需要Liquido在用户完成支付后重定向用户回到您的页面时，您需要在请求中包含此内容。只有当请求参数中的‘paymentFlow’为‘REDIRECT’时，您才可以设置此重定向URL。

Response Body 字段说明

参数 必填 类型 描述
idempotencyKey String 此参数用于幂等目的，交易的唯一标识ID 长度不大于128个字节。
referenceId String 收款票据的唯一标识
amount Long 收款金额. 单位是当前货币的最小结算粒度，例如100=1BRL
country String 国家编码 BR
currency String 收款货币代码，长度为3个字节，BRL
finalAmount Long 用于创建收款订单的最终金额。对于需要转换汇率的收款订单，这个字段的值表示源请求金额被转换后的金额。
finalCurrency String finalAmount的收款货币代码
paymentMethod String 支付方式. 枚举值, CREDIT_CARD
payer JSON 买家个人信息。
transferDetails JSON 交易其他详细信息
description String 交易描述
callbackUrl String 商户接收通知的回调地址. 接收http的post请求.
createTime String 创建时间
scheduledTime String 执行时间
finalStatusTime String 最终状态更新时间. 最终状态，包括"REFUNDED", "FAILED"
transferStatus String 收款状态，枚举值，"SETTLED", "FAILED", "IN_PROGRESS"
transferStatusCode Integer 此次交易的状态码, 200表示交易成功或者进行中, 其他代表失败
transferErrorMsg String 此次交易失败原因
amountDetails JSON 金额详细信息
subMerchantId String 子商户ID。
redirectUrl String 必须重定向此URL给客户以完成付款。当请求参数的“paymentFlow”字段值为“REDIRECT”时，此重定向URL将包含在返回参数内。
merchantRedirectInfo JSON 重定向回商户页面的信息。

transferDetails 对象字段说明

参数 类型 描述
pix JSON pix 相关信息

pix 对象字段说明

参数 类型 描述
qrCode String 二维码
qrCodeType String 二维码类型枚举，DYNAMIC
expirationTime String 支付期限

AmountDetails

参数 类型 描述
taxAmountDetails JSON 税费详情
fxAmountDetails JSON 换汇详情

TaxAmountDetails

参数 类型 描述
taxRate JSON 税率信息
amount Long 本次支付的税费

TaxRate

参数 类型 描述
type String 税费的类型字符串
rate Double 本次支付的税率

FXAmountDetails

参数 类型 描述
fxRate JSON 汇率信息
baseAmount Long 换汇前的金额
targetAmount Long 换汇后的金额

FXRate

参数 类型 描述
timestamp Long 获取汇率的时间
base String 换汇前的货币类型
target String 换回后的货币类型
exchangeRate Double 使用的汇率

Transfer Status

参数 描述
IN_PROGRESS 交易处理中
SETTLED 交易完成
REFUNDING 退款中
REFUNDED 已退款
CANCELLED 取消交易
FAILED 交易失败，异常

Notification Event Type

CHARGE_SUCCEEDED,
CHARGE_FAILED,
CHARGE_CHARGED_BACK,
CHARGE_REFUND_SUCCEEDED,
CHARGE_REFUND_FAILED;
回到页面顶部