Charges

Charges represent individual payment transactions. Use the Charges API to accept payments from customers, authorize transactions for later capture, and view payment history.

POST/v1/charges

Create a charge

Creates a new charge object to process a payment.

Required attributes

Name
amount
Type
integer
Description
Amount in cents to charge (e.g., 1999 for $19.99).
Name
currency
Type
string
Description
Three-letter ISO currency code (e.g., USD, EUR).

Optional attributes

Name
card
Type
object
Description
Card details for direct charging. Alternative to using a token.
Name
token
Type
string
Description
Payment token created by Shift4.js or a payment method ID.
Name
customer
Type
string
Description
ID of an existing customer to charge.
Name
description
Type
string
Description
Description of the charge for your records.
Name
capture
Type
boolean
Description
Whether to immediately capture the payment. Default: true.
Name
metadata
Type
object
Description
Key-value pairs for storing additional information.

Request

const charge = await shift4.charges.create({
  amount: 2999,
  currency: 'USD',
  card: {
    number: '4242424242424242',
    expMonth: 12,
    expYear: 2025,
    cvc: '123',
  },
  description: 'Premium subscription',
});

Response

{
  "id": "char_test_abc123",
  "object": "charge",
  "amount": 2999,
  "currency": "USD",
  "status": "successful",
  "captured": true,
  "description": "Premium subscription",
  "card": {
    "id": "card_test_xyz789",
    "brand": "Visa",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2025
  },
  "created": 1699564800,
  "metadata": {}
}

GET/v1/charges/:id

Retrieve a charge

Retrieves the details of an existing charge.

Path parameters

Name
id
Type
string
Description
The ID of the charge to retrieve.

Request

const charge = await shift4.charges.retrieve('char_test_abc123');

Response

{
  "id": "char_test_abc123",
  "object": "charge",
  "amount": 2999,
  "currency": "USD",
  "status": "successful",
  "captured": true,
  "created": 1699564800
}

GET/v1/charges

List charges

Returns a list of charges sorted by creation date, with the most recent charges first.

Query parameters

Name
limit
Type
integer
Description
Number of charges to return (max 100). Default: 10.
Name
starting_after
Type
string
Description
Cursor for pagination. ID of the charge to start after.
Name
customer
Type
string
Description
Filter by customer ID.

Request

const charges = await shift4.charges.list({
  limit: 25,
});

Response

{
  "object": "list",
  "data": [
    {
      "id": "char_test_abc123",
      "amount": 2999,
      "currency": "USD",
      "status": "successful"
    }
  ],
  "has_more": false,
  "total_count": 1
}

POST/v1/charges/:id/capture

Capture a charge

Captures a previously authorized charge. Only works on charges created with capture: false.

Path parameters

Name
id
Type
string
Description
The ID of the charge to capture.

Optional attributes

Name
amount
Type
integer
Description
Amount to capture (in cents). Must be less than or equal to the authorized amount.

Request

const charge = await shift4.charges.capture('char_test_abc123', {
  amount: 2999,
});

Response

{
  "id": "char_test_abc123",
  "status": "successful",
  "captured": true,
  "amount": 2999,
  "amount_captured": 2999
}