银行转账
银行转账是巴西市场上主流的支付方式之一。每一个银行转账请求的返回参数里,都会包含Liquido的银行账号信息,商户可以使用这些信息给终端用户创建支付凭证。
HTTP请求
POST
/v1/payments/charges/bank_transfer
Request Headers
{
"Content-Type": "application/json",
"Authorization": "Bearer {{access_token}}",
"x-api-key": "{{api_key}}"
}
Request Body
{
"idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
"amount": 100,
"currency": "BRL",
"country": "BR",
"paymentMethod": " BANK_TRANSFER",
"paymentFlow": "DIRECT",
"payer": {
"name": "Thiago Gabriel",
"email": "thiago@example.com",
"document": {
"documentId": "53033315550",
"type": "CPF"
},
"phone": "+55 81987654321",
"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": "shipping phone",
"email": "thiago@example.com",
"address": {
"street": "street name",
"number": "building number",
"complement": "unit, apt, etc.",
"district": "district, neighborhood, etc.",
"city": "city name",
"state": "state, state code",
"zipCode": "zip code, postal code",
"country": "BR"
}
}
},
"callbackUrl": "http://api.client.com/notifications",
"description": "hello world",
"subMerchantId": "UUID"
}
Content-Type: application/json
{
"transferStatusCode": 200,
"transferErrorMsg": null,
"idempotencyKey": "BankTransfer-20220909001",
"referenceId": "BankTransfer-20220909001",
"paymentMethod": "BANK_TRANSFER",
"amount": 100,
"currency": "BRL",
"country": "BR",
"finalAmount": 100,
"finalCurrency": "BRL",
"createTime": "2022-09-09 00:02:22 GMT-07:00",
"scheduledTime": null,
"finalStatusTime": null,
"payer": {
"name": "Thiago Gabriel",
"document": {
"documentId": "00740886967",
"type": "CPF"
},
"email": "thiago@example.com",
"phone": "+55 81987654321",
"billingAddress": {
"street": "street name",
"number": "building number",
"complement": "unit, apt, etc.",
"district": "district, neighborhood, etc.",
"city": "city name",
"state": "state, state code",
"zipCode": "zip code, postal code",
"country": "BR"
}
},
"transferStatus": "IN_PROGRESS",
"description": "hello world",
"callbackUrl": "https://api.liquido.com/v1/cashier/callback/",
"transferDetails": {
"bankTransfer": {
"expirationTime": "2022-09-16 00:02:22 GMT-07:00",
"bankAccountInfo": {
"bankCode": "332",
"beneficiaryName": "antonio silva",
"bankAccountNumber": "286435",
"bankAccountType": "CHECKING",
"bankBranchId": "0001",
"ispb": "13140088",
"document": {
"documentId": "60131743007",
"type": "CPF"
}
}
}
},
"subMerchantId": "UUID"
}
通知 / 回调
Content-Type: application/json
{
"eventType": "CHARGE_SUCCEEDED",
"data": {
"chargeDetails": {
"transferStatusCode": 200,
"transferErrorMsg": null,
"idempotencyKey": "BankTransfer-20220909001",
"referenceId": "BankTransfer-20220909001",
"paymentMethod": "BANK_TRANSFER",
"amount": 100,
"currency": "BRL",
"country": "BR",
"finalAmount": 100,
"finalCurrency": "BRL",
"createTime": "2022-09-09 00:02:22 GMT-07:00",
"scheduledTime": null,
"finalStatusTime": null,
"payer": {
"name": "Thiago Gabriel",
"document": {
"documentId": "00740886967",
"type": "CPF"
},
"email": "thiago@example.com",
"phone": "+55 81987654321",
"billingAddress": {
"street": "street name",
"number": "building number",
"complement": "unit, apt, etc.",
"district": "district, neighborhood, etc.",
"city": "city name",
"state": "state, state code",
"zipCode": "zip code, postal code",
"country": "BR"
}
},
"transferStatus": "IN_PROGRESS",
"description": "hello world",
"callbackUrl": "https://api.liquido.com/v1/cashier/callback/",
"transferDetails": {
"bankTransfer": {
"expirationTime": "2022-09-16 00:02:22 GMT-07:00",
"bankAccountInfo": {
"bankCode": "332",
"beneficiaryName": "antonio silva",
"bankAccountNumber": "286435",
"bankAccountType": "CHECKING",
"bankBranchId": "0001",
"ispb": "13140088",
"document": {
"documentId": "60131743007",
"type": "CPF"
}
}
}
},
"subMerchantId": "UUID"
}
}
}
HTTP 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 | 交易方式,枚举值BANK_TRANSFER | |
paymentFlow | String | 交易流程, 如DIRECT 或 REDIRECT | |
payer | JSON | 买家个人信息 | |
orderInfo | JSON | 订单信息 | |
description | String | 描述 | |
callbackUrl | String | 接收交易状态变更通知的地址,接收post请求 | |
sandboxStatus | String | 仅用于DEBUG, 用来指定返回中的transfer status,有以下几种状态: APPROVED, DECLINED, ERROR | |
subMerchantId | String | 子商户ID。商户类型为PSP时必填。 | |
riskData | JSON | 支付的风险信息。MERCHANT_APP_NAME 或 MERCHANT_WEBSITE 在riskData中必须填一个。 请参考这里查看更多详情。 |
创建一个带风控信息的支付
请参考这里查看更多详情。
Payer 对象字段说明
参数 | 必填 | 类型 | 描述 |
---|---|---|---|
name | String | 名字,全称(入参名字规范:只允许大小写字母,数字和空格的组合。请勿包含西班牙语和葡萄牙语字母,以及其他特殊字符。) | |
String | 邮箱 | ||
document | JSON | 可确认身份的证件,CPF或CNPJ | |
phone | String | 电话号码,需包含“+55”的前缀。 | |
billingAddress | JSON | 账单邮寄地址 |
Document 对象字段说明
参数 | 必填 | 类型 | 描述 |
---|---|---|---|
documentId | String | 证件号码 | |
type | String | 证件类型,暂时支持CPF或者CNPJ |
BillingAddress 对象字段说明
参数 | 必填 | 类型 | 描述 |
---|---|---|---|
zipCode | String | 邮政编码 | |
state | String | 州 | |
city | String | 城市 | |
street | String | 街道 | |
number | String | 门牌号 |
OrderInfo 对象字段说明
参数 | 必填 | 类型 | 描述 |
---|---|---|---|
orderId | String | 订单号 | |
shippingInfo | JSON | 运输信息 |
ShippingInfo 对象字段说明
参数 | 必填 | 类型 | 描述 |
---|---|---|---|
name | String | 名称 | |
phone | String | 电话号码,需包含“+55”的前缀。 | |
String | 邮箱地址 | ||
address | JSON | 地址信息,结构和billingAddress一致 |
Response Body 字段说明
参数 | 类型 | 描述 |
---|---|---|
transferStatus | String | 汇款状态,枚举值,"SETTLED", "FAILED", "IN_PROGRESS" |
transferStatusCode | Integer | 此次交易的状态码, 200表示交易成功或者进行中, 其他代表失败 |
transferErrorMsg | String | 此次交易失败原因 |
referenceId | String | 此次交易的ID |
idempotentKey | String | 此参数用于幂等目的,交易的唯一标识ID,长度不大于128个字节。 |
amount | Long | 收款金额 |
country | String | 国家编码 BR |
currency | String | 收款货币代码,长度为3个字节,BRL |
finalAmount | Long | 用于创建收款订单的最终金额。对于需要转换汇率的收款订单,这个字段的值表示源请求金额被转换后的金额。 |
finalCurrency | String | finalAmount的收款货币代码 |
paymentMethod | String | 支付方式. 枚举值, BANK_TRANSFER |
payer | JSON | 付款人信息 |
description | String | 描述信息 |
callbackUrl | String | 商户接收通知的回调地址. 接收http的get请求 |
createTime | String | 创建时间 |
scheduledTime | String | 执行时间 |
finalStatusTime | String | 最终状态更新时间. 最终状态,包括"REFUNDED", "FAILED" |
subMerchantId | String | 子商户ID。 |
transferDetails | JSON | 交易信息详情,里面会包含银行账号信息的内容,您可以使用这些信息给您的终端用户创建支付凭证。 |
TransferDetails 对象字段说明
参数 | 类型 | 描述 |
---|---|---|
bankTransfer | JSON | 银行转账的详细信息 |
BankTransfer 对象字段说明
参数 | 类型 | 描述 |
---|---|---|
expirationTime | String | 这个支付的过期时间 |
bankAccountInfo | JSON | 银行账号信息 |
BankAccountInfo 对象字段说明
参数 | 类型 | 描述 |
---|---|---|
bankCode | String | 银行代码,3位数字 |
beneficiaryName | String | 受益人名称,例如 BRL_LIQUIDO |
bankAccountNumber | String | 受益人账号 |
bankBranchId | String | 银行分行Id |
bankAccountType | String | 受益人账号类型,例如 ContaCorrente |
ispb | String | 银行的ISPB, 用途和缩写bankCode一致, 8位数字 |
document | String | 可确认身份的证件,CPF或CNPJ |
支付状态
参数 | 描述 |
---|---|
IN_PROGRESS | 交易处理中 |
SETTLED | 交易完成 |
REFUNDING | 退款中 |
REFUNDED | 已退款 |
CHARGED_BACK | 拒付 |
FAILED | 交易失败,异常 |