跳转至

PicPay

创建一个PICPAY支付二维码。

HTTP请求

POST /v1/payments/charges/pic_pay

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": "PIC_PAY",
    "paymentFlow": "DIRECT",
    "payer": {
        "name": "Thiago Gabriel",
        "email": "thiago@example.com",
        "document": {
            "documentId": "53012345678",
            "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": "+55 81987654321",  
            "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": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "PIC_PAY",
    "amount": 100,
    "currency": "BRL",
    "country": "BR",
    "finalAmount": 100,
    "finalCurrency": "BRL",
    "createTime": "2022-02-20 19:22:32 GMT-08:00",
    "scheduledTime": "2022-02-20 21:19:23 GMT-08:00",
    "finalStatusTime": null,
    "payer": {
        "name": "Thiago Gabriel",
        "document": {
            "documentId": "53012345678",
            "type": "CPF"
        },
        "email": "thiago@example.com",
        "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"
        }
    },
    "transferDetails": {
        "picPay": {
            "paymentUrl": "",
            "picPayQrcode": {
                "content": "",
                "base64": ""
            },
            "expirationTime": "2022-03-08T22:53:18-03:00",
        }
    },
    "transferStatus": "IN_PROGRESS",
    "description": "hello world",
    "callbackUrl": "http://api.client.com/notifications",
    "subMerchantId": "UUID"
}

通知 / 回调

Content-Type: application/json
{
    "eventType": "CHARGE_SUCCEEDED",
    "data":  {
        "chargeDetails": {
            "transferStatusCode": 200,
            "transferErrorMsg": null,
            "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
            "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
            "paymentMethod": "PIC_PAY",
            "amount": 100,
            "currency": "BRL",
            "country": "BR",
            "finalAmount": 100,
            "finalCurrency": "BRL",
            "createTime": "2022-03-01 17:53:18 GMT-08:00",
            "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
            "finalStatusTime": null,
            "payer": {
                "name": "Thiago Gabriel",
                "document": {
                    "documentId": "53012345678",
                    "type": "CPF"
                },
                "email": "thiago@example.com",
                "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"
                }
            },
            "transferDetails": {
                "picPay": {
                    "paymentUrl": "",
                    "picPayQrcode": {
                        "content": "",
                        "base64": ""
                    },
                    "expirationTime": "2022-03-08T22:53:18-03:00",
                }
            },
            "transferStatus": "SETTLED",
            "description": "hello world",
            "callbackUrl": "http://api.client.com/notifications",
            "subMerchantId": "UUID"
        }
    }
}

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 交易方式，枚举，当前场景使用PIC_PAY
paymentFlow String 交易流程, 如DIRECT 或 REDIRECT. 当前只支持DIRECT
payer JSON 买家个人信息。
orderInfo JSON 订单信息。可缺省
description String 描述。
callbackUrl String 接收交易状态变更通知的地址。接收post请求。
subMerchantId String 子商户ID。商户类型为PSP时必填。
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一致

Response Body Details

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

transferDetails 对象字段说明

参数 类型 描述
picPay JSON pic_pay 相关信息

picPay 对象字段说明

参数 类型 描述
paymentUrl String 支付链接
picPayQrcode JSON picpay支付二维码
expirationTime String 过期时间

picPayQrcode 对象字段说明

参数 类型 描述
content String 二维码的内容
base64 JSON base64编码后的内容

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;
回到页面顶部