# 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
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.moneycollect.com/docs/payment/pre-authorize-a-payment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.