v1

latestOpenAPI 3.1.02026-07-2631427.2 KB

Capture a Hold

Capture the funds of an existing, uncaptured, Hold.

This is the second half of the two-step payment flow, where first a Hold was created with the /holds API or with a Payment Session (capture flag set to false).

The API will create a Charge from the referenced Hold and response with the created Charge information.

post/v1/holds/{id}/capture

Request body

amount_to_capturestring

The amount to capture from the Hold in minor units.

Amount must be less than or equal to the original amount of the Hold.

The field is optional and if not provided will default to the entire Hold.

referencestring

A unique string to reference the Charge created from the Hold. Can be used to reconcile the object with your internal systems.

metadataMetadata

Example request

{
  "amount_to_capture": "10000"
}

Response

Example response

idstring

Unique identifier for Charge object.

resourcestring

String representing the resource type.

amountinteger

Amount recieved, in minor units.

amount_human_readablestring

Amount in human readable format.

amount_refundedinteger

Amount refunded out of the total amount received, in minor units.

calculated_statement_descriptorstring

The full statement descriptor that is displayed on your customers’ bank statements. Allows you to see what the statement descriptor looks like after the static and dynamic portions are combined.

createdstring

Time at which the resource was created. ISO String format.

currencystring

Three-letter ISO currency code, in lowercase.

customerstring

ID of the customer this Charge is for if one exists.

customer_reference_idstring

A unique identifier for your customer, This is a customer ID that identifies the customer that the Charge belongs to.

descriptionstring

A string attached to the resource. Often useful for displaying to users.

disputedboolean

Indicates whether the charge was disputed.

failure_codestring

failure_messagestring

metadataobject

Set of key-value pairs that you can attach to the resource.

paidboolean

Indicates whether the charge was setteled and paid to your bank account.

payment_sessionstring

ID of the Payment Session the Charge was created from if exists.

holdstring

ID of the Hold the Charge was created from if exists.

payment_methodstring

ID of the Payment Method used for the Charge.

refundedboolean

Indicates whether the Charge was refunded, will only be true if the Charge was fully refunded.

referencestring

A unique string to reference the Charge that was entered while creating the resource. Can be used to reconcile the object with your internal systems.

statement_descriptor_suffixstring

Provides information about the payment that customers can see on their charge statements. Concatenated with the statement descriptor that’s set on the account during onboarding the complete statement descriptor, maximum of 22 characters for the concatenated descriptor.

status'succeeded' | 'failed' | 'pending' | 'requires_authentication' | 'requires_confirmation'

Status of the Charge.

Example response

{
  "id": "chrg_146231656762572800",
  "resource": "charge",
  "amount": 10000,
  "amount_human_readable": "100.00",
  "amount_refunded": 0,
  "billing_details": null,
  "calculated_statement_descriptor": "PAYCOM * TEST",
  "created": "2022-09-07T13:40:41.751Z",
  "currency": "usd",
  "customer": "cust_199440887619523584",
  "customer_reference_id": "2s68c46d-8d15-4c2a-ae4c-30ec77abed9f",
  "description": null,
  "disputed": false,
  "failure_code": null,
  "failure_message": null,
  "metadata": {},
  "paid": false,
  "payment_session": null,
  "hold": "hld_220204193980350464",
  "payment_method": "pm_card_202779025452569600",
  "payment_method_details": {
    "type": "card",
    "card": {
      "bin": "424242",
      "brand": "visa",
      "country": "US",
      "exp_month": "11",
      "exp_year": "25",
      "fingerprint": "c5338f1c33863cce001e80648ea80df1068ed5f94dbb4bfb561ed8da8988fe0a",
      "funding": "credit",
      "last4": "4242",
      "network": "visa",
      "security_checks": {
        "address_line1_check": "unavailable",
        "address_postal_code_check": "unavailable",
        "cvc_check": "pass"
      },
      "three_d_secure": null,
      "token": "tok_card_202779025452569600",
      "wallet": null
    }
  },
  "payment_method_options": {
    "card": {
      "accepted_card_brands": [
        "visa",
        "mastercard"
      ],
      "accepted_card_categories": [
        "consumer"
      ],
      "accepted_card_funding": [
        "debit",
        "credit"
      ],
      "accepted_card_jurisdictions": [
        "domestic"
      ],
      "duplicate_card_check": true,
      "enforce_customer_name_as_cardholder_name": false,
      "security_checks": {
        "address_line1_check": false,
        "address_postal_code_check": false,
        "cvv_check": true
      },
      "request_threed_secure": "challenge"
    }
  },
  "refunded": false,
  "refunds": {
    "data": [],
    "url": "/v1/charges/chrg_146231656762572800/refunds"
  },
  "reference": null,
  "shipping": null,
  "statement_descriptor_suffix": "TEST",
  "status": "succeeded"
}