# capture (One-time Payments)

> This API is used to capture the funds of an authorized payment from a user's account, and then transfer the specified payment amount to the merchant's account.

`POST /v1/payments/capture`

This API is used to capture the funds of an authorized payment from a user's account, and then transfer the specified payment amount to the merchant's account. Depending on different scenarios, the authorized payment can be captured in one of the following ways: 

-   Full capture: Capture the total payment amount. 
-   Partial capture: Capture the partial payment amount.  

# Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see： 

-   [Request header](https://docs.antom.com/ac/ams/api_fund.md#ML5ur)
-   [Response header](https://docs.antom.com/ac/ams/api_fund.md#WWH90)

> **Note**: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
>
> -   If the data type of a field is Integer and its value is `20`, set it as "`20`". 
> -   If the data type of a field is Boolean and its value is `true`, set it as "`true`".

## Request parameters

#### captureRequestId (String, REQUIRED)

The unique ID that is assigned by the merchant to identify a capture request. Antom uses this field for idempotence control.

More information:

- This field is an API idempotency field.For capture requests that are initiated with the same value of captureRequestId and reach a final status (S or F), the same result is to be returned for the request.
- Maximum length: 64 characters

#### paymentId (String, REQUIRED)

The unique ID that is assigned by Antom to identify a payment.

More information:

- Maximum length: 64 characters

#### captureAmount (Amount, REQUIRED)

The capture amount that the merchant requests to receive in the transaction currency.

##### currency (String, REQUIRED)

The 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.

More information:

- Maximum length: 3 characters

##### value (Integer, REQUIRED)

The value of the amount as a positive integer in the smallest currency unit. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to `100`; or if the currency is JPY and the amount is ￥1, set the value of this parameter to `1`.  

For details about the smallest currency unit, see [Smallest unit of the currency](https://docs.antom.com/ac/ref/cc.md#ONkIe) .

For details about the minimum payment amount allowed for each payment method, see [Minimum amount rules](https://docs.antom.com/ac/ref/cc.md#q9R5A).

> Note: Due to the currency practices in Indonesia, when the currency is IDR, round the amount with banker's rounding and fix the last two digits of this parameter as `00.`

More information:

- Value range: 1 - unlimited

#### transit (Transit)

Trip information, including trip modes, legs of trips and passenger information.

##### transitType (String)

Trip modes, valid values are:

-   `FLIGHT`: indicates that the trip mode is by plane.
-   `TRAIN`: indicates that the trip mode is by train.
-   `CRUISE`: indicates that the trip mode is by cruise.
-   `COACH`: indicates that the trip mode is by coach.

##### agentCode (String)

International Air Transport Association (IATA) code of the travel agent handling the reservation.

More information:

- Maximum length: 8 characters

##### agentName (String)

The name of the travel agency that made the reservation.

More information:

- Maximum length: 32 characters

##### ticketNumber (String)

A unique identifier for the ticket, typically formatted as IATA 3-letter airline code followed by a 10-digit number assigned by the airline.

More information:

- Maximum length: 15 characters

##### ticketIssuerCode (String)

The IATA two-word airline code of the ticketing agency.

More information:

- Maximum length: 2 characters

##### restrictedTicketIndicator (String)

Indicates whether the ticket is refundable. Valid values include:

-   `0`: Indicates the ticket is refundable.
-   `1`: Indicates the ticket is not refundable.

More information:

- Maximum length: 2 characters

##### legs (Array<Leg>)

Information about sections of the trip, including departure time, arrival time, departure address, arrival address, transportation company name, carrier code and service type.

More information:

- Maximum size: 10 elements

###### departureTime (Datetime)

Time of departure for this leg of the trip.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

###### arrivalTime (Datetime)

Time of arrival for this leg of the trip.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

###### departureAddress (Object)

Departure address for this leg of the trip.

###### region (String)

The 2-letter country or region code. For more information, see [ISO 3166 Country Codes](https://www.iso.org/obp/ui/#search) standard.

More information:

- Maximum length: 2 characters

###### state (String)

The state, country, or province.

More information:

- Maximum length: 8 characters

###### city (String)

The city, district, suburb, town, or village name.

More information:

- Maximum length: 32 characters

###### address1 (String)

Address line 1, for example, the street address, PO box, and company name.

More information:

- Maximum length: 256 characters

###### address2 (String)

Address line 2, for example, the apartment, suite, unit, and building information.

More information:

- Maximum length: 256 characters

###### arrivalAddress (Object)

Destination address for this leg of the trip.

###### region (String)

The 2-letter country or region code. For more information, see [ISO 3166 Country Codes](https://www.iso.org/obp/ui/#search) standard.

More information:

- Maximum length: 2 characters

###### state (String)

The state, country, or province.

More information:

- Maximum length: 8 characters

###### city (String)

The city, district, suburb, town, or village name.

More information:

- Maximum length: 32 characters

###### address1 (String)

Address line 1, for example, the street address, PO box, and company name.

More information:

- Maximum length: 256 characters

###### address2 (String)

Address line 2, for example, the apartment, suite, unit, and building information.

More information:

- Maximum length: 256 characters

###### carrierNo (String)

International Air Transport Association (IATA) code is obtained from the Official Airline Guide or its equivalent.

More information:

- Maximum length: 2 characters

###### carrierName (String)

Company name of the transportation service provider for this leg of the trip.

More information:

- Maximum length: 128 characters

###### departureAirportCode  (String)

IATA code for the originating airport for this leg of the trip.

More information:

- Maximum length: 3 characters

###### arrivalAirportCode (String)

IATA code for the destination airport for this leg of the trip.

More information:

- Maximum length: 3 characters

###### fareBasis (String)

Code used to identify the basic rules of segment fares. This code is defined by the airline to identify ticket attributes, such as cabin class (e.g., business class), fare rules (e.g., discounted/non-refundable changes), or promotional conditions.

> **Note**: This code only contains letters (A-Z), numbers (0-9), and spaces. The use of special characters is prohibited.

More information:

- Maximum length: 16 characters

###### couponNumber (String)

An electronic coupon number used to identify a flight segment in a ticket. Each ticket may contain multiple electronic coupons, each corresponding to an independent flight segment.

> **Note**: This number must be unique within the same ticket but can be duplicated across different tickets.

More information:

- Maximum length: 2 characters

###### flightNumber (String)

The identifier assigned to a specific flight. Typically 1 to 4 numeric digits, optionally followed by a suffix letter.

More information:

- Maximum length: 5 characters

##### passenger (Object)

Information about the passenger of the trip.

###### passengerName (Object)

The name of the passenger.

###### firstName (String)

First name.

More information:

- Maximum length: 32 characters

###### middleName (String)

Middle name.

More information:

- Maximum length: 32 characters

###### lastName (String)

Last name.

More information:

- Maximum length: 32 characters

###### fullName (String)

Full name.

More information:

- Maximum length: 128 characters

###### passengerCode (String)

The unique identifier assigned by the air carrier to a passenger for accurately identifying the passenger in the airline system.

More information:

- Maximum length: 32 characters

##### ancillaryData (Object)

Information about an ancillary purchase.

###### connectedTicketNumber (String)

The airline ticket number linked to this ancillary purchase. If the ancillary product is associated with a flight ticket (like a baggage fee), enter that flight ticket number here.

More information:

- Maximum length: 15 characters

###### services (Array<Service>)

Information about the services included in an ancillary purchase.

###### categoryCode (String)

Category code for the ancillary services offered. Retrieve the codes from the International Air Transport Association (IATA).

More information:

- Maximum length: 4 characters

###### subCategoryCode (String)

Subcategory code for the ancillary service category. Retrieve codes from the International Air Transport Association (IATA).

More information:

- Maximum length: 4 characters

## Response parameters

#### result (Result, REQUIRED)

The result of the API call. If this API is successfully called, the capture is successful.

##### resultCode (String, REQUIRED)

The result code that indicates the detailed processing result.

More information:

- Maximum length: 64 characters

##### resultStatus (String, REQUIRED)

Result status. Valid values are:

-   `S`: Indicates that the result status is successful.
-   `F`: Indicates that the result status is failed.
-   `U`: Indicates that the result status is unknown.

##### resultMessage (String, REQUIRED)

Result message that explains the result code.

More information:

- Maximum length: 256 characters

#### captureRequestId (String)

The unique ID that is assigned by a merchant to identify a capture request.

> Note: This parameter is returned when the capture status is successful.

More information:

- Maximum length: 64 characters

#### captureId (String)

The unique ID that is assigned by Antom to identify a capture.

> Note: This parameter is returned when the capture status is successful.

More information:

- Maximum length: 64 characters

#### paymentId (String)

The unique ID that is assigned by Antom to identify a payment.

> Note: This parameter is returned when the capture status is successful.

More information:

- Maximum length: 64 characters

#### captureAmount (Amount)

The capture amount that the merchant requests to receive in the transaction currency.

> Note: This parameter is returned when the capture status is successful.

##### currency (String, REQUIRED)

The 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.

More information:

- Maximum length: 3 characters

##### value (Integer, REQUIRED)

The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a 0-decimal currency). 

For details about the smallest currency unit, see [Smallest unit of the currency](https://docs.antom.com/ac/ref/cc.md#ONkIe).

More information:

- Value range: 1 - unlimited

#### captureTime (Datetime)

The time when Antom captures the payment.

> Note: This parameter is returned when the capture status is successful.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

#### acquirerReferenceNo (String)

The unique ID assigned by the non-Antom acquirer for the transaction.

More information:

- Maximum length: 64 characters

## Result/Error codes

| Code | Value | Message | Further action |
| --- | --- | --- | --- |
| SUCCESS | S | Success | The capture is successful, no further action is needed. |
| ACCESS_DENIED | F | The access is denied.  | Contact Antom Technical Support for detailed reasons. |
| AUTH_CANCELLED | F | The payment authorization is canceled.  | Use a new paymentRequestId to initiate a payment. |
| AUTH_EXPIRED | F | The payment authorization is expired.  | Use a new paymentRequestId to initiate a payment. |
| AUTH_NOT_FOUND | F | The payment authorization is not found.  | Contact Antom Technical Support for detailed reasons. |
| CAPTURE_AMOUNT_EXCEED_AUTH_LIMIT | F | The total capture amount exceeds the limit of the authorized payment amount. | Create a new capture request by using an amount less than or equal to the authorized payment amount, or contact Antom Technical Support. |
| CAPTURE_IN_PROCESS | U | The capture is processing.  | Wait for the notification from Antom or inquiry about the capture result. |
| CURRENCY_NOT_SUPPORT | F | The currency is not supported. | Check the currency used in the request, such as the capture currency. If the issue persists, contact Antom Technical Support for detailed reasons. |
| MULTI_CAPTURE_NOT_SUPPORTED | F | The transaction does not support multiple captures.  | Contact Antom Technical Support for detailed reasons. |
| INVALID_CONTRACT | F | The parameter values in the contract do not match those in the current transaction.  | Check whether the parameter values in the contract match those in the current transaction. If the values match, contact Antom Technical Support to troubleshoot the issue. |
| NO_PAY_OPTIONS | F | No payment methods are available. | Contact Antom Technical Support for detailed reasons. |
| ORDER_IS_CANCELED | F | The transaction is canceled. | Use a new paymentRequestId to initiate a payment. |
| ORDER_STATUS_INVALID | F | The transaction status is abnormal. The payment cannot be captured.  | Check the transaction status.  If the values match, contact Antom Technical Support to troubleshoot the issue. |
| PARAM_ILLEGAL | F | The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong. | Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid. |
| PAYMENT_COUNT_EXCEED_LIMIT | F | The number of captures exceeds the limit that is specified by the payment method. | Contact Antom Technical Support to know the specific limit. |
| PROCESS_FAIL | F | The capture failed. | Do not retry. Human intervention is usually needed. It is recommended that you contact Antom Technical Support to troubleshoot the issue. |
| REPEAT_REQ_INCONSISTENT | F | The submitted request exists, and the parameter values of this request are not consistent with those of the existing request.  | Ensure all the fields in the requests are the same or use a new paymentRequestId to initiate a payment. |
| RISK_REJECT | F | The request is rejected because of risk control. | Prompt the user that the request is rejected because of failed risk control. |
| USER_AMOUNT_EXCEED_LIMIT | F | The capture amount exceeds the user payment limit.  | Create a new capture by using an amount less than or equal to the user payment limit, or contact the user or the issuing bank. |
| USER_BALANCE_NOT_ENOUGH | F | The user's balance is insufficient for the capture. | Contact Antom Technical Support for detailed reasons. |
| USER_NOT_EXIST | F | The user's account does not exist on the payment method side.  | Contact the user or the issuing bank. |
| USER_STATUS_ABNORMAL | F | The user's account status is abnormal on the payment method side.  | Contact Antom Technical Support to know the specific reasons. |
| UNKNOWN_EXCEPTION | U | The API call has failed, which is caused by unknown reasons. | Call the interface again to resolve the issue. If the problem persists, contact Antom Technical Support. |

## Request

### CAPTURE_SUCCESSFUL

```json
{
  "paymentId": "20220919194010890100111740275820195",
  "captureRequestId": "capture_cangxi_lj_20220920_005914_845",
  "captureAmount": {
    "currency": "HKD",
    "value": "10"
  }
}
```

### CAPTURE_RELATED_AIRLINE_INFO

```json
{
  "captureAmount": {
    "currency": "SGD",
    "value": "2"
  },
  "captureRequestId": "CAPTURE_qiyue202501092206",
  "captureType": "FINAL",
  "paymentId": "20250109194010800100188580271422374",
  "transit": {
    "agentCode": "98222147",
    "agentName": "Antom Vacations",
    "legs": [
      {
        "arrivalAddress": {
          "address1": "Gongzhuan road",
          "address2": "wen yi road2",
          "city": "hz",
          "region": "CN",
          "state": "zj",
          "zipCode": "518000"
        },
        "arrivalAirportCode": "SZX",
        "arrivalTime": "2025-05-16T12:01:01+08:00",
        "carrierName": "Antom vacations",
        "carrierNo": "AA",
        "couponNumber": "1",
        "departureAddress": {
          "address1": "Gongzhuan road",
          "address2": "wen yi road2",
          "city": "hz",
          "region": "CN",
          "state": "zj",
          "zipCode": "100000"
        },
        "departureAirportCode": "HGH",
        "fareBasis": "HL7WNR",
        "flightNumber": "20241"
      }
    ],
    "passenger": {
      "passengerName": {
        "firstName": "Lei",
        "fullName": "Lei Li",
        "lastName": "Li"
      }
    },
    "restrictedTicketIndicator": "0",
    "ticketNumber": "02721187251",
    "transitType": "FLIGHT"
  }
}
```

## Response

```json
{
  "acquirerReferenceNo": "2022091919031300010740267587902",
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "success."
  },
  "captureTime": "2022-09-19T09:59:17-07:00",
  "paymentId": "20220919194010890100111740275820195",
  "captureRequestId": "capture_cangxi_lj_20220920_005914_845",
  "captureId": "20220919194010890100111740275850565",
  "captureAmount": {
    "currency": "HKD",
    "value": "10"
  }
}
```