跳转至

预授权与结算

创建信用卡预授权

预授权可以让你在顾客的银行账号中,冻结部分资金,直到交易实际发生时再扣除。例如,当使用信用卡进行酒店预定的时候。

要进行这样的交易流程,首先你需要创建一个预授权,然后再进行预授权的结算。

HTTP请求

POST /v1/payments/charges/card

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab1",
    "amount": 10000,
    "country": "CO",
    "currency": "COP",
    "paymentMethod": "CREDIT_CARD",
    ...  # other basic request fields
    "capture": false,
    "subMerchantId": "UUID",
    ...  # other basic request fields
}
Response
{
    "transferStatusCode": 200,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab1",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab1",
    "paymentMethod": "CREDIT_CARD",
    "amount": 10000,
    "currency": "COP",
    "finalAmount": 10000,
    "finalCurrency": "COP",
    "country": "CO",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    ...  # other basic response fields
    "transferDetails": {
        "card": {
            "cardInfo": {
                "cardHolderName": "card_holder_name",
                "expirationMonth": 9,
                "expirationYear": 2024,
                "brand": "VISA",
                "bin": "458124",
                "last4": "0000"
            },
            "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
        }
    },
    "transferStatus": "AUTHORIZED",
    "description": "this is a test pay",
    "subMerchantId": "UUID"
}

HTTP Headers 字段说明

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

Request Body 字段说明

参数 必填 类型 描述
capture Boolean 必须设置为false以创建一个预授权
subMerchantId String 子商户ID。商户类型为PSP时必填。

结算预授权

HTTP请求

POST /v1/payments/charges/card/capture/{{idempotencyKey}}

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "amount": 1000
}
Response
{
    "transferStatusCode": 200,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab1",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab1",
    "paymentMethod": "CREDIT_CARD",
    "amount": 10000,
    "currency": "COP",
    "finalAmount": 10000,
    "finalCurrency": "COP",
    "country": "CO",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    ...  # other basic response fields
    "transferDetails": {
        "card": {
            "cardInfo": {
                "cardHolderName": "card_holder_name",
                "expirationMonth": 9,
                "expirationYear": 2024,
                "brand": "VISA",
                "bin": "458124",
                "last4": "0000"
            },
            "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
        }
    },
    "transferStatus": "SETTLED",
    "description": "this is a test pay",
    "subMerchantId": "UUID"
}

HTTP Headers 字段说明

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

PATH and Query Parameters 字段说明

参数 类型 描述
idempotencyKey String 需要结算的预授权交易的幂等键

Request Body 字段说明

参数 必填 类型 描述
amount Long 预授权的实际结算金额。默认为预授权冻结金额的全额。它可以等于或小于,但不能大于所冻结的金额。

取消预授权

HTTP请求

POST /v1/payments/charges/cancel/{{idempotencyKey}}

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Response
{
    "transferStatusCode": 200,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab1",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab1",
    "paymentMethod": "CREDIT_CARD",
    "amount": 10000,
    "currency": "COP",
    "finalAmount": 10000,
    "finalCurrency": "COP",
    "country": "CO",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    ...  # other basic response fields
    "transferDetails": {
        "card": {
            "cardInfo": {
                "cardHolderName": "card_holder_name",
                "expirationMonth": 9,
                "expirationYear": 2024,
                "brand": "VISA",
                "bin": "458124",
                "last4": "0000"
            },
            "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
        }
    },
    "transferStatus": "CANCELLED",
    "description": "this is a test pay",
    "subMerchantId": "UUID"
}

PATH and Query Parameters 字段说明

参数 类型 描述
idempotencyKey String 需要取消的预授权交易的幂等键
回到页面顶部