跳转至

创建一个支付请求

创建一个信用卡支付

当向Liquido发送信用卡交易请求时，您需要提供信用卡的详细信息。您可以通过直接发送卡的详细信息或者cardId进行请求。 请参考如何创建cardId。

HTTP请求

POST /v1/payments/charges/card

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
使用card info创建一个信用卡支付
Request Body
{
    "idempotencyKey": "d050a33b-05ef-4be6-b01f-1379dd8700c8",
    "amount": 100,
    "currency": "GTQ",
    "country": "GT",
    "paymentMethod": "CREDIT_CARD",
    "paymentFlow": "DIRECT",
    "payer": {
        "document":{
            "documentId":"1234567890101",
            "type":"CUI"
        },
        "name": "username",
        "email": "username@liquido.com",
        "phone": "+50281987654321",
        "billingAddress": {  
            "zipCode": "1001",
            "state": "Buenos Aires",
            "city": "Buenos Aires",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "5940",
            "complement": "casa",
            "country": "GT"
        }
    },
    "card": {
        "cardHolderName":"Captured",
        "cardNumber":"5105105105105100",
        "cvc":"123",
        "expirationMonth":"1",
        "expirationYear":"2028"
    },
    "orderInfo": {  
        "orderId": "test-order-id",  
        "orderReferenceNumber": "test-order-reference-number",
        "shippingInfo": { 
            "name": "shipping test name",  
            "phone": "+50281987654321",  
            "email": "thiago@example.com",
            "address": { 
                "zipCode": "1001",
                "state": "Buenos Aires",
                "city": "Buenos Aires",
                "district": "Jardim Gaivotas",
                "street": "Rua 9 de setembro",
                "number": "5940",
                "complement": "casa",
                "country": "GT"
            }
        }
    },
    "riskData": {
        "PAYER_IP_ADDRESS": "192.0.0.130",
        "PAYER_LOGIN_ID": "1234567890",
        "PAYER_DEVICE_ID": "c9380c4c-bfc3-42c9-9120-22d1db2d53af"
    },
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/",
    "subMerchantId": "UUID"
}
使用card id创建一个信用卡支付

如何获得card id?

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

Request Body
{
    "idempotencyKey": "d050a33b-05ef-4be6-b01f-1379dd8700c8",
    "amount": 100,
    "currency": "GTQ",
    "country": "GT",
    "paymentMethod": "CREDIT_CARD",
    "paymentFlow": "DIRECT",
    "payer": {
        "document":{
            "documentId":"1234567890101",
            "type":"CUI"
        },
        "name": "username",
        "email": "username@liquido.com",
        "phone": "+50281987654321",
        "billingAddress": {  
            "zipCode": "1001",
            "state": "Buenos Aires",
            "city": "Buenos Aires",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "5940",
            "complement": "casa",
            "country": "GT"
        }
    },
    "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237",
    "orderInfo": {  
        "orderId": "test-order-id", 
        "orderReferenceNumber": "test-order-reference-number",
        "shippingInfo": { 
            "name": "shipping test name",  
            "phone": "+50281987654321",  
            "email": "thiago@example.com",
            "address": { 
                "zipCode": "1001",
                "state": "Buenos Aires",
                "city": "Buenos Aires",
                "district": "Jardim Gaivotas",
                "street": "Rua 9 de setembro",
                "number": "5940",
                "complement": "casa",
                "country": "GT"
            }
        }
    },
    "riskData": {
        "PAYER_IP_ADDRESS": "192.0.0.130",
        "PAYER_LOGIN_ID": "1234567890",
        "PAYER_DEVICE_ID": "c9380c4c-bfc3-42c9-9120-22d1db2d53af"
    },
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/",
    "subMerchantId": "UUID"
}
Response
{
    "transferStatusCode": 200,
    "transferErrorMsg": null,
    "idempotencyKey": "d050a33b-05ef-4be6-b01f-1379dd8700c8",
    "referenceId": "d050a33b-05ef-4be6-b01f-1379dd8700c8",
    "paymentFlow": "DIRECT",
    "paymentMethod": "CREDIT_CARD",
    "amount": 100,
    "currency": "GTQ",
    "finalAmount": 100,
    "finalCurrency": "GTQ",
    "country": "GT",
    "createTime": "2025-07-10 12:37:03 UTC",
    "scheduledTime": "2025-07-10 12:37:03 UTC",
    "finalStatusTime": "2025-07-10 12:37:03 UTC",
    "payer": {
        "name": "username",
        "document": {
            "documentId": "1234567890101",
            "type": "CUI"
        },
        "email": "username@liquido.com",
        "phone": "+50281987654321",
        "billingAddress": {
            "street": "Rua 9 de setembro",
            "number": "5940",
            "complement": "casa",
            "district": "Jardim Gaivotas",
            "city": "Buenos Aires",
            "state": "Buenos Aires",
            "zipCode": "1001",
            "country": "GT"
        }
    },
    "transferStatus": "SETTLED",
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/",
    "transferDetails": {
        "card": {
            "cardInfo": {
                "cardHolderName": "Captured",
                "expirationMonth": 1,
                "expirationYear": 2028,
                "brand": "MASTERCARD",
                "bin": "510510",
                "last4": "5100"
            }
        }
    },
    "subMerchantId": "UUID"
}

通知 / 回调

Content-Type: application/json
{
    "eventType": "CHARGE_SUCCEEDED",
    "data":  {
        "chargeDetails": {
              "transferStatusCode": 200,
              "transferErrorMsg": null,
              "idempotencyKey": "d050a33b-05ef-4be6-b01f-1379dd8700c8",
              "referenceId": "d050a33b-05ef-4be6-b01f-1379dd8700c8",
              "paymentFlow": "DIRECT",
              "paymentMethod": "CREDIT_CARD",
              "amount": 100,
              "currency": "GTQ",
              "finalAmount": 100,
              "finalCurrency": "GTQ",
              "country": "GT",
              "createTime": "2025-07-10 12:37:03 UTC",
              "scheduledTime": "2025-07-10 12:37:03 UTC",
              "finalStatusTime": "2025-07-10 12:37:03 UTC",
              "payer": {
                "name": "username",
                "document": {
                  "documentId": "1234567890101",
                  "type": "CUI"
                },
                "email": "username@liquido.com",
                "phone": "+50281987654321",
                "billingAddress": {
                  "street": "Rua 9 de setembro",
                  "number": "5940",
                  "complement": "casa",
                  "district": "Jardim Gaivotas",
                  "city": "Buenos Aires",
                  "state": "Buenos Aires",
                  "zipCode": "1001",
                  "country": "GT"
                }
              },
              "transferStatus": "SETTLED",
              "description": "this is a test pay",
              "callbackUrl": "https://api.client.com/callback/",
              "transferDetails": {
                "card": {
                  "cardInfo": {
                    "cardHolderName": "Captured",
                    "expirationMonth": 1,
                    "expirationYear": 2028,
                    "brand": "MASTERCARD",
                    "bin": "510510",
                    "last4": "5100"
                  }
                }
              },
              "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.01GTQ
country String 国家编号国际缩写码，遵循ISO 3166-1 alpha-2 code标准
currency String 货币代码
paymentMethod String 交易方式，枚举值CARD
paymentFlow String 交易流程, 如DIRECT
payer JSON 买家个人信息。
card JSON 信用卡信息.如果cardId缺省，则card不能为缺省
cardId String 信用卡id. 如果card缺省，则cardId不能为缺省
capture Boolean 设置为false以创建一个信用卡预授权
installments Integer 分期付款次数. 不分期的时候请缺省该参数
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 电话号码，需包含“+502”的前缀。
document JSON 可确认身份的证件，例如CUI.
billingAddress JSON 账单邮寄地址.
document 对象字段说明
参数 必填 类型 描述
documentId String 证件号码
type String 证件类型，支持CUI
billingAddress 对象字段说明
参数 必填 类型 描述
zipCode String 邮政编码.
state String 州.
city String 城市.
district String 区县.
street String 街道.
number String 门牌号.
complement String 补充信息.
country String 国家代码.
orderInfo 对象字段说明
参数 必填 类型 描述
orderId String 订单号
orderReferenceNumber String 订单参考号
shippingInfo JSON 运输信息
shippingInfo 对象字段说明
参数 必填 类型 描述
name String 名称
phone String 电话号码，需包含“+502”的前缀。
email String 邮箱地址
address JSON 地址信息，结构和billingAddress一致
Card 对象字段说明
参数 必填 类型 描述
cardHolderName String 持卡人全称。
cardNumber String 卡号,纯数字字符串,不能有横杠空格等分隔符。
cvc String 信用卡安全码
expirationMonth String 信用卡有效期月份，2位数。
expirationYear String 信用卡有效期年份，4位数。

Response Body 字段说明

参数 类型 描述
transferStatus String 汇款状态
transferStatusCode Integer 此次交易的状态码, 200表示交易成功、进行中或预授权成功, 其他代表失败
transferErrorMsg String 失败时的具体错误信息，请参考2xxx相关状态码的描述
referenceId String 此次交易的ID
idempotencyKey String 此参数用于幂等目的，交易的唯一标识ID 长度不大于128个字节。
amount Long 收款金额
country String 国家编码
currency String 收款货币代码
finalAmount Long 用于创建收款订单的最终金额。对于需要转换汇率的收款订单，这个字段的值表示源请求金额被转换后的金额。
finalCurrency String finalAmount的收款货币代码
paymentMethod String 支付方式. 枚举值, CARD
paymentFlow String 支付流程. 枚举值, DIRECT
payer JSON 付款人信息
transferDetails JSON 交易类型的详细信息
description String 描述信息
callbackUrl String 商户接收通知的回调地址. 接收http的get请求.
createdTime String 创建时间
scheduledTime String 执行时间
finalStatusTime String 最终状态更新时间. 最终状态，包括"REFUNDED", "FAILED"
subMerchantId String 子商户ID。
transferDetails 对象字段说明
参数 类型 描述
card JSON 卡相关信息
card (响应)对象字段说明
参数 类型 描述
cardInfo JSON 卡详细信息
cardId String 卡ID, 使用卡信息支付时不返回，用卡ID支付时会返回
installments Integer 分期付款次数
CardInfo (响应)对象字段说明
参数 类型 描述
cardHolderName String 持卡人姓名
bin String 卡号前6位数字
last4 String 卡号后4位数字
brand String 信用卡组织. 如 VISA, MASTERCARD
expirationMonth Integer 1位数或者2位数的信用卡有效期月份。
expirationYear Integer 信用卡有效期年份，4位数。

支付状态

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

Notification 事件类型

CHARGE_SUCCEEDED,
CHARGE_AUTHORIZED,
CHARGE_FAILED,
CHARGE_CHARGED_BACK,
CHARGE_REFUND_SUCCEEDED,
CHARGE_REFUND_FAILED;

更多的信用卡支付功能

创建一个信用卡预授权

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

创建一个分期付款的信用卡支付

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

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

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

回到页面顶部