# Pre-authorize a payment

### 1 Create a pre-authorized payment

{% tabs %}
{% tab title="Checkout page" %}
When creating Checkout session, set the value of `preAuth` property to 'y'.

* The value is `y`：indicates that the current payment is pre-authorized. After the cardholder completes the authorization, the status of the payment is'uncaptured'. And you need to capture funds, the payment can be finalized.
* The value is `n`：indicates this is an ordinary payment and 'n'is the default value.

```java
// Use your private key
MoneyCollect.apiKey = "test_pr_NWZsa******";

SessionCreateParams params =
                    SessionCreateParams.builder()
                            .setReturnUrl("http://localhost:4242/success.html")
                            .setCancelUrl("http://localhost:4242/cancel.html")
                            .setNotifyUrl("http://localhost:4242/success.html")
                            .setAmountTotal(19 * 100L)
                            .setCurrency("USD")
                            .setOrderNo("C"+System.currentTimeMillis())
                            .setWebsite("https://www.mc.com")
                            .setPreAuth(SessionCreateParams.PreAuth.YES)
                            .build();
Session session = Session.create(params);
```

{% endtab %}

{% tab title="Payment" %}
When creating Payment, set the value of `preAuth` property to 'y'.

* The value is `y`：indicates that the current payment is pre-authorized. After the cardholder completes the payment, the status of the payment is'uncaptured'. And you need to capture funds, the payment can be finalized.
* The value is `n`：indicates this is an ordinary payment and 'n'is the default value.

```java
// Use your private key
MoneyCollect.apiKey = "test_pr_NWZsa******";

PaymentCreateParams params = 
             PaymentCreateParams.builder()
                    .setAmount(14 * 100L)
                    .setCurrency("USD")
                    .setOrderNo("MC"+System.currentTimeMillis()) 
                    .setIp("103.48.140.12")
                    .setPaymentMethod("{PAYMENT_METHOD_ID}")
                    .setConfirmationMethod(PaymentCreateParams.ConfirmationMethod.AUTOMATIC)
                    .setPreAuth(PaymentCreateParams.PreAuth.YES)
                    .build();
Payment payment =  Payment.create(params);
```

{% endtab %}
{% endtabs %}

> When a payment is pre-authorized, but it cannot be captured or canceled in 7days, MoneyCollect will automatically cancel this payment.

### 2 Capture a pre-authorized payment

1. Use API Capture a Payment to capture payment in 'uncaptured' status.

* `paymentId` The ID of the payment you capture.
* `comment` the description for capture.

```java
// Use your private key
MoneyCollect.apiKey = "test_pr_NWZsa******";

PaymentCaptureParams params = PaymentCaptureParams.builder()
                          .setPaymentId("py_1451067513881452545")
                          .setComment("capture all")
                          .build();
Payment payment = Payment.capture(params);
return JSONObject.toJSONString(payment);
```

2\.  Use MoneyCollect Dashboard to capture

> Capture a pre-authorized payment, only supports to capture full amount. That is to say, we don't support partially capture a payment.

### 3 Cancel the pre-authorization

Use API Cancel a Payment to cancel the payment in 'uncaptured' status. 

* `paymentId` the ID of the payment you cancel.
* `cancellationReason` The reason why you cancel the pre-authorization.

```java
// Use your private key
MoneyCollect.apiKey = "test_pr_NWZsa******";

PaymentCancelParams params = PaymentCancelParams.builder()
                    .setPaymentId("py_1451067513881452545")
                    .setCancellationReason("I want to cancel.")
                    .build();
Payment payment = Payment.cancel(params);
return JSONObject.toJSONString(payment);
```

You can also cancel a Pre-auth payment in your MoneyCollect Dashboard.

## Zero-Amount Authorization

This section describes how to perform **zero-amount authorization** to validate and bind a customer’s payment method **without charging any funds**, and how to reuse the saved payment method for future transactions.

### 1. Merchant Tokenization Configuration

Before using zero-amount authorization, the merchant must enable the Tokenization capability.

**Configuration Requirement:**\
Please contact your account manager to apply for activation of the **Tokenization product**.

### 2. Zero-Amount Authorization Creation Flow

The zero-amount authorization flow consists of the following steps:

1. Create a Customer
2. Create a PaymentMethod
3. Create a Payment (Zero-Amount Authorization)

#### 2.1 Create Customer

**Description:**\
Create a customer object to represent an end user.\
The returned `customerId` should be uniquely mapped to the merchant’s internal user identifier.

**Request Example**

```json
{
    "address": {
        "city": "Asheville",
        "country": "US",
        "line1": "3968 Fidler Drive",
        "line2": "",
        "postalCode": "28806",
        "state": "North Carolina"
    },
    "description": "",
    "email": "xxxx@aaabbb.com",
    "firstName": "Mark",
    "lastName": "Merrill",
    "phone": "2106276464"
}
```

**Response Example**

```json
{
    "code": "success",
    "msg": "success",
    "data": {
        "id": "cus_1938157433067143170",
        "email": "xxxx@aaabbb.com",
        "firstName": "Mark",
        "lastName": "Merrill",
        "phone": "2106276464",
        "description": "",
        "address": {
            "city": "Asheville",
            "country": "US",
            "line1": "3968 Fidler Drive",
            "line2": "",
            "postalCode": "28806",
            "state": "North Carolina"
        },
        "shipping": null,
        "created": "2025-06-26T08:48:35.925Z"
    }
}
```

***

#### 2.2 Create PaymentMethod

**Description:**\
Create a payment method object to securely collect and store the customer’s card information.\
A `paymentMethod` ID will be returned for future use.

**Request Example**

```json
{
    "billingDetails": {
        "address": {
            "city": "Asheville",
            "country": "US",
            "line1": "3968 Fidler Drive",
            "line2": "",
            "postalCode": "28806",
            "state": "North Carolina"
        },
        "email": "xxxx@aaabbb.com",
        "firstName": "Mark",
        "lastName": "Merrill",
        "phone": "2106276464",
        "description": ""
    },
    "card": {
        "cardNo": "4242424242424242",
        "expMonth": "04",
        "expYear": "2028",
        "securityCode": "123"
    },
    "type": "card",
    "merchantPaySite": "https://test.com/"
}
```

**Response Example**

```json
{
    "code": "success",
    "msg": "success",
    "data": {
        "id": "pm_1938159585009336322",
        "type": "card",
        "billingDetails": {
            "firstName": "Mark",
            "lastName": "Merrill",
            "phone": "2106276464",
            "email": "xxxx@aaabbb.com",
            "address": {
                "city": "Asheville",
                "country": "US",
                "line1": "3968 Fidler Drive",
                "line2": "",
                "postalCode": "28806",
                "state": "North Carolina"
            }
        },
        "created": "2025-06-26T08:57:08.987Z",
        "customerId": null,
        "card": {
            "brand": "Visa",
            "country": "GB",
            "expMonth": "04",
            "expYear": "2028",
            "fingerprint": "KB2kvSZ3i2un0lmfwIc873kvRJJem4AAEvA/fo3HPPo=",
            "last4": "4242",
            "tokenType": null
        },
        "boleto": null,
        "pix": null,
        "creditCardBrazil": null
    }
}
```

***

#### 2.3 Create Payment (Zero-Amount Authorization)

**Description:**\
Create a payment request to perform zero-amount authorization.\
When both `customerId` and `paymentMethod` are provided and `setupFutureUsage` is set to `on`, the system will bind the payment method to the customer for future transactions.

#### Important Parameters

| Parameter          | Description                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| `customerId`       | The unique identifier of the customer. Used to bind the payment method to a specific end user.     |
| `paymentMethod`    | The identifier of the payment method (card) to be authorized and bound to the customer.            |
| `setupFutureUsage` | Indicates that the payment method will be saved and tokenized for future use. Must be set to `on`. |
| `amount`           | The transaction amount. Can be set to `0` for card validation without charging the customer.       |

**Request Example**

```json
{
    "amount": "0",
    "confirmationMethod": "automatic",
    "currency": "USD",
    "customerId": "cus_1938157433067143170",
    "description": "test tokenization",
    "ip": "192.168.3.1",
    "confirm": "true",
    "lineItems": [
        {
            "amount": 10,
            "currency": "USD",
            "description": "test tokenization",
            "images": [
                "https://www.aaabbb.com/xxxxxx.png"
            ],
            "name": "test",
            "quantity": 1
        }
    ],
    "notifyUrl": "https://www.aaabbb.com/notifyUrl",
    "orderNo": "47598388037375697",
    "paymentMethod": "pm_1938159585009336322",
    "preAuth": "n",
    "receiptEmail": "xxxx@aaabbb.com",
    "returnUrl": "https://www.aaabbb.com/returnUrl",
    "setupFutureUsage": "on",
    "statementDescriptor": "TEST",
    "statementDescriptorSuffix": "",
    "website": "https://test.com/"
}
```

**Response Example**

```json
{
    "code": "success",
    "msg": "success",
    "data": {
        "id": "pt_1938161587181322242",
        "amount": "1000",
        "currency": "USD",
        "confirmationMethod": "automatic",
        "customerId": "cus_1938157433067143170",
        "description": "test tokenization",
        "paymentMethod": "pm_1938159585009336322",
        "paymentMethodTypes": [
            "card"
        ],
        "paymentMethodType": "card",
        "receiptEmail": "xxxx@aaabbb.com",
        "setupFutureUsage": "on",
        "orderNo": "47598388037375697",
        "notifyUrl": "https://www.aaabbb.com/notifyUrl",
        "returnUrl": "https://www.aaabbb.com/returnUrl",
        "website": "https://test.com/",
        "ip": "192.168.3.1",
        "preAuth": "n",
        "statementDescriptor": "TEST",
        "clientSecret": "pt_1938161587181322242_secret_564C4368F6A6523E5E8099C88E549FB7",
        "canceledAt": null,
        "cancellationReason": null,
        "amountReceived": "0",
        "amountCapturable": "0",
        "created": "2025-06-26T09:05:06.346Z",
        "riskInfo": {
            "riskScore": 0,
            "riskMessage": "risk_pass"
        },
        "status": "succeeded",
        "displayStatus": "succeeded",
        "errorCode": null,
        "errorMessage": null,
        "invoiceId": null,
        "fromChannel": null,
        "use3D": false
    }
}
```

***

### 3. Charging with a Saved Payment Method in Future Scenarios

After completing zero-amount authorization, merchants can initiate future payments by reusing the saved `customerId` and `paymentMethod`.

> **Note:**\
> Subsequent transactions may trigger **3D Secure authentication**, depending on the card network and risk evaluation.

***

#### Request Example

```json
{
    "amount": "1000",
    "confirmationMethod": "automatic",
    "currency": "USD",
    "customerId": "cus_1938157433067143170",
    "description": "test tokenization",
    "ip": "192.168.3.1",
    "confirm": "true",
    "notifyUrl": "https://www.aaabbb.com/notifyUrl",
    "orderNo": "57598388037375697",
    "paymentMethod": "pm_1938159585009336322",
    "preAuth": "n",
    "receiptEmail": "xxxx@aaabbb.com",
    "returnUrl": "https://www.aaabbb.com/returnUrl",
    "setupFutureUsage": "on",
    "statementDescriptor": "TEST",
    "statementDescriptorSuffix": "",
    "website": "https://test.com/"
}
```

#### Response Example

```json
{
    "code": "success",
    "msg": "success",
    "data": {
        "id": "pt_1938163722635706369",
        "amount": "1000",
        "currency": "USD",
        "confirmationMethod": "automatic",
        "customerId": "cus_1938157433067143170",
        "description": "test tokenization",
        "paymentMethod": "pm_1938159585009336322",
        "paymentMethodTypes": [
            "card"
        ],
        "paymentMethodType": "card",
        "receiptEmail": "xxxx@aaabbb.com",
        "setupFutureUsage": "on",
        "orderNo": "57598388037375697",
        "notifyUrl": "https://www.aaabbb.com/notifyUrl",
        "returnUrl": "https://www.aaabbb.com/returnUrl",
        "website": "https://test.com/",
        "ip": "192.168.3.1",
        "preAuth": "n",
        "statementDescriptor": "TEST",
        "clientSecret": "pt_1938163722635706369_secret_F1F86B847E81E1CE0AF4BDBA6D9F6620",
        "canceledAt": null,
        "cancellationReason": null,
        "amountReceived": "0",
        "amountCapturable": "0",
        "created": "2025-06-26T09:13:35.478Z",
        "riskInfo": {
            "riskScore": 0,
            "riskMessage": "risk_pass"
        },
        "status": "succeeded",
        "displayStatus": "succeeded",
        "errorCode": null,
        "errorMessage": null,
        "invoiceId": null,
        "fromChannel": null,
        "use3D": false
    }
}
```