跳转至

单次支付

PayCash单次支付所生成的交易号(reference number)仅可被支付一次。

支付者在哥伦比亚的线下支付网点进行支付时，需要同时提供本接口生成的交易号(reference number/referencia)以及一个网点对应的协议号(agreement code/convenio)给收银员以完成交易。 交易号能在接口返回的“referenceNumber”字段获取。而协议号则需以线下支付网点对应，具体请参考协议号对照表。

HTTP请求

POST /v1/payments/charges/paycash

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "co-20221001-0001",
    "amount": 50000,
    "currency": "COP",
    "country": "CO",
    "paymentMethod": "PAY_CASH",
    "paymentFlow": "DIRECT",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "billingAddress": {  
            "zipCode": "03400",
            "state": "CDMX",
            "city": "Álamos",
            "street": "Simón Bolívar",
            "number": "12121"
        }
    },
    "orderInfo": {  
        "orderId": "test-order-id",  
        "shippingInfo": { 
            "name": "shipping test name",   
            "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": "CO"
            }
        }
    },
    "riskData": {
        "ipAddress": "192.0.0.130"
    },
    "callbackUrl":"https://api.client.com/callback/",
    "description": "this is a test pay",
    "expirationDate": "2022-10-31",
    "recurring": false,
    "subMerchantId": "UUID"
}
Content-Type: application/json
{
    "transferStatusCode": 200,
    "idempotencyKey": "co-20221001-0001",
    "referenceId": "co-20221001-0001",
    "paymentMethod": "PAY_CASH",
    "amount": 50000,
    "currency": "COP",
    "finalAmount": 50000,
    "finalCurrency": "COP",
    "country": "CO",
    "createTime": "2022-10-01 09:44:29 UTC",
    "scheduledTime": "2022-10-01 09:44:33 UTC",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "billingAddress": {
            "street": "Simón Bolívar",
            "number": "12121",
            "city": "Álamos",
            "state": "CDMX",
            "zipCode": "03400"
        }
    },
    "transferStatus": "IN_PROGRESS",
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/",
    "transferDetails": {
        "payCash": {
            "referenceNumber": "2701665308673817",
            "expirationDate": "2022-10-31",
            "recurring": false
        }
    },
    "subMerchantId": "UUID"
}

通知 / 回调

Content-Type: application/json
{
    "eventType":"CHARGE_SUCCEEDED",
    "data":{
        "chargeDetails":{
            "transferStatusCode": 200,
            "idempotencyKey": "co-20221001-0001",
            "referenceId": "co-20221001-0001",
            "paymentMethod": "PAY_CASH",
            "amount": 50000,
            "currency": "COP",
            "finalAmount": 50000,
            "finalCurrency": "COP",
            "country": "CO",
            "createTime": "2022-10-01 09:44:29 UTC",
            "scheduledTime": "2022-10-01 09:44:33 UTC",
            "payer": {
                "name": "username",
                "email": "username@liquido.com",
                "billingAddress": {
                    "street": "Simón Bolívar",
                    "number": "12121",
                    "city": "Álamos",
                    "state": "CDMX",
                    "zipCode": "03400"
                }
            },
            "transferStatus":"SETTLED",
            "description": "this is a test pay",
            "callbackUrl": "https://api.client.com/callback/",
            "transferDetails": {
                "payCash": {
                    "referenceNumber": "2701665308673817",
                    "expirationDate": "2022-10-31",
                    "recurring": false,
                    "paymentTime": "2022-10-06 00:21:20"
                }
            },
            "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
country String 国家编号国际缩写码，遵循ISO 3166-1 alpha-2 code标准, 如哥伦比亚CO
currency String 货币代码，如哥伦比亚COP
paymentMethod String 支付方式. 枚举值PAY_CASH
paymentFlow String 交易流程, 如DIRECT 或 REDIRECT
payer JSON 买家个人信息
orderInfo JSON 订单信息
riskData JSON 风险控制信息
description String 描述
callbackUrl String 接收交易状态变更通知的地址。接收post请求。
expirationDate String 交易过期时间，格式：yyyy-MM-dd
recurring Boolean 交易分单次或多次付清，目前仅支持单次，值固定为:false
subMerchantId String 子商户ID。商户类型为PSP时必填。

Response Body 字段说明

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

对象字段说明

Payer
参数 必填 类型 描述
name String 名字，全称（入参名字规范：只允许大小写字母，数字和空格的组合。请勿包含西班牙语和葡萄牙语字母，以及其他特殊字符。）
email String 邮箱
phone String 电话号码，需包含“+57”的前缀。
billingAddress JSON 账单邮寄地址
BillingAddress
参数 必填 类型 描述
zipCode String 邮政编码
state String 州
city String 城市
street String 街道
number String 门牌号
OrderInfo
参数 必填 类型 描述
orderId String 订单号
shippingInfo JSON 运输信息
ShippingInfo
参数 必填 类型 描述
name String 名称
phone String 电话号码，需包含“+57”的前缀。
email String 邮箱地址
address JSON 地址信息，结构和billingAddress一致
RiskData
参数 必填 类型 描述
ipAddress String 客户请求源IP地址
TransferDetails
参数 类型 描述
payCash JSON PayCash支付的详细信息
PayCash
参数 类型 描述
referenceNumber String 支付者在支付时，需要提供的交易号(reference number/referencia)。需要注意的是除此之外，用户还需根据其支付网点，提交对应的协议号。
expirationDate String 过期日期 哥伦比亚时间 "yyyy-MM-dd"
recurring Boolean 是否可以多次付款
paymentTime String 实际支付时间 哥伦比亚时间 "yyyy-MM-dd HH:mm:ss"

支付状态

参数 描述
IN_PROGRESS 交易处理中
SETTLED 交易完成
EXPIRED 交易过期
CANCELLED 交易取消
FAILED 交易失败，异常

Notification 事件类型

CHARGE_SUCCEEDED,
CHARGE_FAILED,
CHARGE_CHARGED_BACK,
CHARGE_REFUND_SUCCEEDED,
CHARGE_REFUND_FAILED;

协议号对照表

线下网点 协议号
Efecty 112766
Refacil Don't need an agreement code.
Acciones y valores Don't need an agreement code.
Banco de Bogotá Don't need an agreement code.
APUESTAS NACIONALES (Corresponsal Banco de Bogotá) 22506
BEMOVIL (Corresponsal Banco de Bogotá) 22506
CB CLARO (Corresponsal Banco de Bogotá) 22506
COMERCIAL CARD (Corresponsal Banco de Bogotá) 22506
CONSUERTE (Corresponsal Banco de Bogotá) 22506
COOPENESA (Corresponsal Banco de Bogotá) 22506
EDEQ (Corresponsal Banco de Bogotá) 22506
FULLCARGA (Corresponsal Banco de Bogotá) 22506
JER (Corresponsal Banco de Bogotá) 22506
MAFEPHONE (Corresponsal Banco de Bogotá) 22506
MAXI SERVICIOS (Corresponsal Banco de Bogotá) 22506
MOVIL RED (Corresponsal Banco de Bogotá) 22506
PEQUEÑAS SUPERFICIES CREDIBANCO (Corresponsal Banco de Bogotá) 22506
PEQUEÑAS SUPERFICIES REDEBAN (Corresponsal Banco de Bogotá) 22506
PRACTISISTEMAS (Corresponsal Banco de Bogotá) 22506
PUNTO DE PAGO (Corresponsal Banco de Bogotá) 22506
PUNTORED (Corresponsal Banco de Bogotá) 22506
SEAPTO (Corresponsal Banco de Bogotá) 22506
SU CHANCE (Corresponsal Banco de Bogotá) 22506
SUPERPAGOS (Corresponsal Banco de Bogotá) 22506
回到页面顶部