预授权与结算

创建信用卡预授权

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

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

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-067861d87ab0",
    "amount": 1000,
    "country": "PE",
    "currency": "PEN",
    "paymentMethod": "CREDIT_CARD",
    ...  # other basic request fields
    "capture": false,
    "subMerchantId": "UUID",
    ...  # other basic request fields
}

Response

{
    "transferStatusCode": 200,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "CREDIT_CARD",
    "amount": 1000,
    "currency": "PEN",
    "finalAmount": 1000,
    "finalCurrency": "PEN",
    "country": "PE",
    "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-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "CREDIT_CARD",
    "amount": 1000,
    "currency": "PEN",
    "finalAmount": 1000,
    "finalCurrency": "PEN",
    "country": "PE",
    "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-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "CREDIT_CARD",
    "amount": 1000,
    "currency": "1000",
    "finalAmount": 1000,
    "finalCurrency": "1000",
    "country": "100",
    "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	需要取消的预授权交易的幂等键