跳转至

Nequi转账

集成指引

Nequi的支付模式会因为“phone”请求字段传值而不同。 当“phone”请求字段有完整值时，支付消息通知将会发送到用户的Nequi APP上，用户需要去到Nequi APP的通知中心找到这条支付消息通知进而完成剩余支付流程。 当“phone”请求字段为空值或者没有此请求字段时，返回参数将包含paymentUrl，用户在这个url里填写完相关信息之后会生成二维码，用户需要到Nequi APP上扫描这个二维码来完成支付。

HTTP请求

POST /v1/payments/charges/nequi

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "amount": 200000,
    "currency": "COP",
    "country": "CO",
    "paymentMethod": "NEQUI",
    "paymentFlow": "DIRECT",
    "nequi": {
        "phone": "+573983956309"
    },
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "document": {
            "documentId": "42243309114",
            "type": "CC"
        },
        "phone": "+57 3123456789",
        "billingAddress": {  
            "zipCode": "111111",
            "state": "Cundinamarca",
            "city": "Bogotá",
            "street": "Apartamento 502, Torre I",
            "number": "Calle 34 # 56 - 78"
        }
    },
    "orderInfo": {  
        "orderId": "test-order-id",  
        "shippingInfo": { 
            "name": "shipping test name",  
            "phone": "shipping phone",  
            "address": { 
                "street": "street name",
                "number": "building number",
                "complement": "unit, apt, etc.",
                "district": "district, neighborhood, etc.",
                "city": "city name",
                "state": "state, state code",
                "zipCode": "111111",
                "country": "CO"
            }
        }
    },
    "riskData": {
        "ipAddress": "192.0.0.130"
    },
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/",
    "subMerchantId": "UUID"
}
Content-Type: application/json
{
    "transferStatusCode": 200,
    "transferErrorMsg": null,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "NEQUI",
    "amount": 200000,
    "currency": "COP",
    "country": "CO",
    "finalAmount": 200000,
    "finalCurrency": "COP",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    "finalStatusTime": "2022-03-01 17:53:18 GMT-08:00",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "document": {
            "documentId": "42243309114",
            "type": "CC"
        },
        "phone": "+57 3123456789",
        "billingAddress": {  
            "zipCode": "111111",
            "state": "Cundinamarca",
            "city": "Bogotá",
            "street": "Apartamento 502, Torre I",
            "number": "Calle 34 # 56 - 78"
        }
    },
    "transferDetails": {
        "nequi": {
            "phone": "+573983956309"
        }
    },
    "transferStatus": "SETTLED",
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/",
    "subMerchantId": "UUID"
}
Content-Type: application/json
{
    "transferStatusCode": 200,
    "transferErrorMsg": null,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "NEQUI",
    "amount": 200000,
    "currency": "COP",
    "country": "CO",
    "finalAmount": 200000,
    "finalCurrency": "COP",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    "finalStatusTime": "2022-03-01 17:53:18 GMT-08:00",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "document": {
            "documentId": "42243309114",
            "type": "CC"
        },
        "phone": "+57 3123456789",
        "billingAddress": {  
            "zipCode": "111111",
            "state": "Cundinamarca",
            "city": "Bogotá",
            "street": "Apartamento 502, Torre I",
            "number": "Calle 34 # 56 - 78"
        }
    },
    "transferDetails": {
        "nequi": {
            "expiresAt": 1695272400,
            "paymentUrl": "https://secure.payzen.lat/t/iagftbij"
        }
    },
    "transferStatus": "SETTLED",
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/",
    "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": "NEQUI",
                "amount": 200000,
                "currency": "COP",
                "country": "CO",
                "finalAmount": 200000,
                "finalCurrency": "COP",
                "createTime": "2022-03-01 17:53:18 GMT-08:00",
                "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
                "finalStatusTime": "2022-03-01 17:53:18 GMT-08:00",
                "payer": {
                    "name": "username",
                    "email": "username@liquido.com",
                    "document": {
                        "documentId": "42243309114",
                        "type": "CC"
                    },
                    "phone": "+57 3123456789",
                    "billingAddress": {  
                        "zipCode": "111111",
                        "state": "Cundinamarca",
                        "city": "Bogotá",
                        "street": "Apartamento 502, Torre I",
                        "number": "Calle 34 # 56 - 78"
                    }
                },
            "transferStatus": "SETTLED",
            "transferDetails": {
                "nequi": {
                    "phone": "+573983956309"
                }
            },
            "description": "this is a test pay",
            "callbackUrl": "https://api.client.com/callback/",
            "subMerchantId": "UUID"
        }
    }
}

HTTP Headers 字段说明

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

Request Body 字段说明

参数 必填 类型 描述
idempotencyKey String 商户系统创建的唯一ID， 长度不大于128个字节。
amount Long 转账金额，单位是货币最小粒度，如100=1COP。最低交易金额为2000COP
country String 国家编号国际缩写码，遵循ISO 3166-1 alpha-2 code标准, 如哥伦比亚CO
currency String 货币编码，如哥伦比亚COP
paymentMethod String 交易方式，枚举值NEQUI
paymentFlow String 交易流程, 如DIRECT或REDIRECT
payer JSON 买家个人信息
orderInfo JSON 订单信息
riskData JSON 风险控制信息
description String 描述
callbackUrl String 接收交易状态变更通知的地址，接收post请求
nequi JSON Nequi相关支付信息
subMerchantId String 子商户ID。商户类型为PSP时必填。

Payer 对象字段说明

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

BillingAddress 对象字段说明

参数 必填 类型 描述
zipCode String 邮政编码
state String 州
city String 城市
street String 街道
number String 门牌号

Nequi 对象字段说明

Parameter Required Type Description
phone String 注册Nequi账号时绑定的手机号码。需包含“+57”的前缀。
当这个字段有完整值时，支付模式是用户通过Nequi APP的通知中心来完成支付。
当这个字段为空值或者没有此请求字段时，支付模式是用户通过Nequi APP扫描QR code来完成支付。

Document 对象字段说明

Parameter Required Type Description
documentId String 证件号码
(字段仅当对象有被提供时必填)
type String 证件类型，如CC、CE、NIT或TI
(字段仅当对象有被提供时必填)

OrderInfo 对象字段说明

参数 必填 类型 描述
orderId String 订单号
(字段仅当对象有被提供时必填)
shippingInfo JSON 运输信息

ShippingInfo 对象字段说明

参数 必填 类型 描述
name String 名称
phone String 电话号码，需包含“+57”的前缀。
(字段仅当对象有被提供时必填)
email String 邮箱地址
address JSON 发货地址
(字段仅当对象有被提供时必填)

ShippingAddress 对象字段说明

Parameter Required Type Description
zipCode String 邮政编码
state String 州
(字段仅当对象有被提供时必填)
city String 城市
(字段仅当对象有被提供时必填)
street String 街道
(字段仅当对象有被提供时必填)
number String 门牌号
(字段仅当对象有被提供时必填)

RiskData 对象字段说明

参数 必填 类型 描述
ipAddress String 客户请求源IP地址

Response Body 字段说明

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

TransferDetails 对象字段说明

参数 类型 描述
nequi JSON 注册Nequi账号时绑定的手机号码。只有当请求参数里面的“phone”字段有完整值时，此字段才会包含在返回参数里。
expiresAt Long 交易过期时间的时间戳。只有当请求参数里的“phone”字段为空值或者没有“phone”请求字段时，此字段才会包含在返回参数里。
paymentUrl String 必须重定向此URL给客户以生成付款二维码。只有当请求参数里的“phone”字段为空值或者没有“phone”请求字段时，此字段才会包含在返回参数里。

Nequi TransferDetails 对象字段说明

参数 类型 描述
phone String 注册Nequi账号时绑定的手机号码

支付状态

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

Notification 事件类型

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