Sign in
Payments

Record a Chargeback

Record a chargeback for a Payment by its ID, and optionally restrict the Customer from making new or recurring payments. Recording a chargeback does not prevent any further operations on the payment, such as capture or reversal.

post/payments/{id}/record-chargeback

Path parameters

idstring required

Request body

blacklistCustomerboolean

Whether to also blacklist the customer associated with the payment

Example request

{
  "customerRestrictions": {
    "restrictReason": "The customer is restricted due to compliance issues"
  }
}

Response

OK

createdAtstring date-time required

The date and time when the entity was created.

updatedAtstring date-time nullable required

The date and time when the entity was last updated.

idstring required

ID of the payment

status'open' | 'requires_action' | 'succeeded' | 'cancelled' required

Status of the payment

displayStatus'retrying' | 'chargeback' | 'reversed' | 'cancelled' | 'partially_reversed' | 'succeeded' | 'uncaptured' | 'incomplete' | 'failed' | 'unattempted' required

A user-friendly aggregate status for display purposes

amountnumber required

Payment amount in minor currency, e.g. 1500 for 15.00 USD

notestring nullable

Optional note for the payment. Only available from the dashboard or the API using a secret key.

currency'usd' | 'eur' | 'gbp' | 'cad' | 'aud' | 'pln' | 'czk' | 'sek' | 'dkk' required

Currency of the payment

amountReversednumber required

Amount reversed for the payment

amountCapturednumber required

Amount captured for the payment

isCapturedboolean required

Indicates if the payment has been captured

isRedirectRequiredboolean required

Indicates if a redirect is required for the payment

isReversedboolean required

Indicates if the payment has been partially reversed

isFullyReversedboolean required

Indicates if the payment has been fully reversed

isRecoveredboolean required

Whether the payment recovered after one or more retry attempts and eventually succeeded.

isRetryingboolean required

Whether the payment is currently in a retrying state after a failed attempt.

isChargebackedboolean

Whether a chargeback has been recorded for this payment. Only available from the dashboard or the API using a secret key.

chargebackRecordedAtstring date-time nullable

The timestamp when a chargeback was recorded for this payment. Only available from the dashboard or the API using a secret key.

authorizedAtstring date-time nullable

The timestamp when an authorization was recorded for this payment. Only available from the dashboard or the API using a secret key.

capturedAtstring date-time nullable

The timestamp when a capture was recorded for this payment. Only available from the dashboard or the API using a secret key.

reversedAtstring date-time nullable

The timestamp when a reversal was recorded for this payment. Only available from the dashboard or the API using a secret key.

initiator'customer' | 'merchant' required

The initiator of the payment, indicating who initiated the payment.

offSessionType'recurring' | 'unscheduled' | 'null' nullable required

The off-session type of the payment. Only present for merchant-initiated payments.

statementDescriptorstring nullable

Statement to be shown on bank statement. Only available from the dashboard or the API using a secret key.

latestMessagestring nullable required

Latest message available for the payment. This message is non-sensitive and may be displayed to the customer.

latestDeclineType'soft_decline' | 'hard_decline' | 'null' nullable

The decline type for the latest transaction. Only available from the dashboard or the API using a secret key.

checkoutKeystring

The checkout key for this payment, used for client-side payment processing by the Checkout SDK.

metadataobject nullable required

Metadata for the payment.

Example response

{
  "createdAt": "2024-02-18T12:00:00Z",
  "updatedAt": "2024-02-21T12:15:00Z",
  "id": "pay_2QC7PqoUeOxQEWscJJt6B3PkvyL",
  "status": "succeeded",
  "displayStatus": "succeeded",
  "amount": 1500,
  "note": "This is a note for the payment",
  "currency": "usd",
  "amountCaptured": 1500,
  "isCaptured": true,
  "isRecovered": true,
  "isRetrying": true,
  "chargebackRecordedAt": "2026-01-15T10:30:00.000Z",
  "authorizedAt": "2026-01-15T10:30:00.000Z",
  "capturedAt": "2026-01-15T10:35:00.000Z",
  "reversedAt": "2026-01-20T14:00:00.000Z",
  "initiator": "customer",
  "offSessionType": "recurring",
  "statementDescriptor": "Some product",
  "latestMessage": "Payment was declined by the issuing bank.",
  "latestDeclineType": "hard_decline",
  "action": {
    "redirectUrl": "https://example.com"
  },
  "checkoutKey": "ck_live_abc123def456",
  "metadata": {},
  "attribution": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "summer_sale",
    "utm_term": "running+shoes",
    "utm_content": "banner_a",
    "utm_id": "utm_123",
    "utm_contentid": "content_123",
    "ref_id": "ref_abc",
    "fbclid": "fbclid_abc",
    "cmpid": "cmp_123"
  },
  "retry": {
    "attempts": 2,
    "nextAmount": 999
  },
  "cart": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "currency": "eur",
    "items": [
      {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "currency": "usd",
        "description": "Pro Plan",
        "amount": 1500,
        "lineAmount": 3000,
        "quantity": 2,
        "price": {
          "createdAt": "2024-02-18T12:00:00Z",
          "updatedAt": "2024-02-21T12:15:00Z",
          "metadata": {
            "key1": "value1",
            "key2": "value2"
          },
          "id": "price_2R4e2xDqbww8ewmkIYWE1A6Zcfp",
          "type": "recurring",
          "active": true,
          "name": "My Digital Subscription",
          "amount": 1500,
          "quantity": 1,
          "currency": "usd",
          "product": {
            "createdAt": "2024-02-18T12:00:00Z",
            "updatedAt": "2024-02-21T12:15:00Z",
            "metadata": {
              "key1": "value1",
              "key2": "value2"
            },
            "id": "prod_2QC7PqoUeOxQEWscJJt6B3PkvyL",
            "active": true,
            "name": "My product",
            "description": "Best selling product",
            "statementDescriptor": "Face Yoga subscription",
            "category": "digital",
            "sku": "FY-YOGA-MAT-01"
          },
          "recurringSchedule": {
            "intervalUnit": "month",
            "intervalCount": 1,
            "trial": {
              "intervalUnit": "day",
              "intervalCount": 7,
              "amount": 199
            }
          }
        }
      }
    ]
  },
  "paymentMethodOptions": {
    "captureMethod": "automatic",
    "captureDelay": 7,
    "recurringCaptureMethod": "automatic",
    "recurringCaptureDelay": 7,
    "card": {
      "mode": "cascade",
      "gatewayProfile": {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "id": "gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL",
        "active": true,
        "title": "Profile #1",
        "integration": "stripe",
        "environment": "test"
      },
      "cascade": {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "name": "My Cascade",
        "description": "Simple cascade",
        "active": true,
        "algorithm": "weightedRoundRobin"
      },
      "captureMethod": "automatic",
      "captureDelay": 7,
      "recurringCaptureMethod": "automatic",
      "recurringCaptureDelay": 7
    },
    "paypal": {
      "mode": "direct",
      "gatewayProfile": {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "id": "gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL",
        "active": true,
        "title": "Profile #1",
        "integration": "stripe",
        "environment": "test"
      },
      "captureMethod": "automatic",
      "captureDelay": 7,
      "recurringCaptureMethod": "automatic",
      "recurringCaptureDelay": 7
    },
    "applePay": {
      "mode": "direct",
      "gatewayProfile": {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "id": "gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL",
        "active": true,
        "title": "Profile #1",
        "integration": "stripe",
        "environment": "test"
      },
      "captureMethod": "automatic",
      "captureDelay": 7,
      "recurringCaptureMethod": "automatic",
      "recurringCaptureDelay": 7
    }
  },
  "customer": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "id": "cus_2QC7PqoUeOxQEWscJJt6B3PkvyL",
    "email": "user@gmail.com",
    "name": "John Doe",
    "phoneNumber": "+1234567890",
    "dateOfBirth": "2020-01-01",
    "gender": "male",
    "restrictReason": "Customer restricted due to suspicious activity",
    "isRestricted": true
  },
  "paymentMethod": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "id": "pm_2QC7PqoUeOxQEWscJJt6B3PkvyL",
    "type": "card",
    "customer": "cus_2QC7PqoUeOxQEWscJJt6B3PkvyL",
    "card": {
      "brand": "amex",
      "lastFour": "1234",
      "bin": "123456",
      "expMonth": "12",
      "expYear": "2025",
      "cardholderName": "John Doe"
    },
    "applePay": {
      "displayName": "MasterCard 1234"
    }
  },
  "latestTransaction": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "status": "authorized",
    "authentication": "not_requested",
    "amount": 1500,
    "initiator": "customer",
    "statementDescriptor": "Hello World",
    "amountCaptured": 1500,
    "isCaptured": true,
    "chargebackRecordedAt": "2026-01-15T10:30:00.000Z",
    "captureMethod": "automatic",
    "currency": "usd",
    "processorId": "ch_1J8lZpJ9j1bSv2Jr6sVjXZ1N",
    "gatewayProfile": {
      "createdAt": "2024-02-18T12:00:00Z",
      "updatedAt": "2024-02-21T12:15:00Z",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "id": "gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL",
      "active": true,
      "title": "Profile #1",
      "integration": "stripe",
      "environment": "test"
    },
    "paymentMethod": {
      "createdAt": "2024-02-18T12:00:00Z",
      "updatedAt": "2024-02-21T12:15:00Z",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "id": "pm_2QC7PqoUeOxQEWscJJt6B3PkvyL",
      "type": "card",
      "customer": "cus_2QC7PqoUeOxQEWscJJt6B3PkvyL",
      "card": {
        "brand": "amex",
        "lastFour": "1234",
        "bin": "123456",
        "expMonth": "12",
        "expYear": "2025",
        "cardholderName": "John Doe"
      },
      "applePay": {
        "displayName": "MasterCard 1234"
      }
    }
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.