单次支付

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"
            }
        }
    },
    "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	订单信息
description	String	描述
callbackUrl	String	接收交易状态变更通知的地址。接收post请求。
expirationDate	String	交易过期时间，格式：yyyy-MM-dd
recurring	Boolean	交易分单次或多次付清，目前仅支持单次，值固定为:false
subMerchantId	String	子商户ID。商户类型为PSP时必填。
riskData	JSON	支付的风险信息。MERCHANT_APP_NAME 或 MERCHANT_WEBSITE 在riskData中必须填一个。请参考这里查看更多详情。

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

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

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一致

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