FileMaster

Edit File: charge-request.md

# Charge Request

Defines the parameters that can be included in the body of
a request to the [Charge](api-endpoint:Transactions-Charge) endpoint.

Deprecated - recommend using [CreatePayment](api-endpoint:Payments-CreatePayment)

## Structure

`ChargeRequest`

## Fields

| Name | Type | Tags | Description | Getter | Setter |
| --- | --- | --- | --- | --- | --- |
| `idempotencyKey` | `string` | Required | A value you specify that uniquely identifies this transaction among transactions you've created. If you're unsure whether a particular transaction succeeded, you can reattempt it with the same idempotency key without worrying about double-charging the buyer. See [Idempotency keys](https://developer.squareup.com/docs/working-with-apis/idempotency) for more information. **Constraints**: *Minimum Length*: `1`, *Maximum Length*: `192` | getIdempotencyKey(): string | setIdempotencyKey(string idempotencyKey): void |
| `amountMoney` | [`Money`](../../doc/models/money.md) | Required | Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. | getAmountMoney(): Money | setAmountMoney(Money amountMoney): void |
| `cardNonce` | `?string` | Optional | A payment token generated from the [Card.tokenize()](https://developer.squareup.com/reference/sdks/web/payments/objects/Card#Card.tokenize) that represents the card to charge. The application that provides a payment token to this endpoint must be the _same application_ that generated the payment token with the Web Payments SDK. Otherwise, the nonce is invalid. Do not provide a value for this field if you provide a value for `customer_card_id`. **Constraints**: *Maximum Length*: `192` | getCardNonce(): ?string | setCardNonce(?string cardNonce): void |
| `customerCardId` | `?string` | Optional | The ID of the customer card on file to charge. Do not provide a value for this field if you provide a value for `card_nonce`. If you provide this value, you _must_ also provide a value for `customer_id`. **Constraints**: *Maximum Length*: `192` | getCustomerCardId(): ?string | setCustomerCardId(?string customerCardId): void |
| `delayCapture` | `?bool` | Optional | If `true`, the request will only perform an Auth on the provided card. You can then later perform either a Capture (with the [CaptureTransaction](api-endpoint:Transactions-CaptureTransaction) endpoint) or a Void (with the [VoidTransaction](api-endpoint:Transactions-VoidTransaction) endpoint). Default value: `false` | getDelayCapture(): ?bool | setDelayCapture(?bool delayCapture): void |
| `referenceId` | `?string` | Optional | An optional ID you can associate with the transaction for your own purposes (such as to associate the transaction with an entity ID in your own database). This value cannot exceed 40 characters. **Constraints**: *Maximum Length*: `40` | getReferenceId(): ?string | setReferenceId(?string referenceId): void |
| `note` | `?string` | Optional | An optional note to associate with the transaction. This value cannot exceed 60 characters. **Constraints**: *Maximum Length*: `60` | getNote(): ?string | setNote(?string note): void |
| `customerId` | `?string` | Optional | The ID of the customer to associate this transaction with. This field is required if you provide a value for `customer_card_id`, and optional otherwise. **Constraints**: *Maximum Length*: `50` | getCustomerId(): ?string | setCustomerId(?string customerId): void |
| `billingAddress` | [`?Address`](../../doc/models/address.md) | Optional | Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). | getBillingAddress(): ?Address | setBillingAddress(?Address billingAddress): void |
| `shippingAddress` | [`?Address`](../../doc/models/address.md) | Optional | Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). | getShippingAddress(): ?Address | setShippingAddress(?Address shippingAddress): void |
| `buyerEmailAddress` | `?string` | Optional | The buyer's email address, if available. This value is optional, but this transaction is ineligible for chargeback protection if it is not provided. | getBuyerEmailAddress(): ?string | setBuyerEmailAddress(?string buyerEmailAddress): void |
| `orderId` | `?string` | Optional | The ID of the order to associate with this transaction. If you provide this value, the `amount_money` value of your request must __exactly match__ the value of the order's `total_money` field. **Constraints**: *Maximum Length*: `192` | getOrderId(): ?string | setOrderId(?string orderId): void |
| `additionalRecipients` | [`?(ChargeRequestAdditionalRecipient[])`](../../doc/models/charge-request-additional-recipient.md) | Optional | The basic primitive of multi-party transaction. The value is optional. The transaction facilitated by you can be split from here. If you provide this value, the `amount_money` value in your additional_recipients must not be more than 90% of the `amount_money` value in the charge request. The `location_id` must be the valid location of the app owner merchant. This field requires the `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission. This field is currently not supported in sandbox. | getAdditionalRecipients(): ?array | setAdditionalRecipients(?array additionalRecipients): void |
| `verificationToken` | `?string` | Optional | A token generated by SqPaymentForm's verifyBuyer() that represents customer's device info and 3ds challenge result. | getVerificationToken(): ?string | setVerificationToken(?string verificationToken): void |

## Example (as JSON)

```json
{
  "additional_recipients": [
    {
      "amount_money": {
        "amount": 20,
        "currency": "USD"
      },
      "description": "Application fees",
      "location_id": "057P5VYJ4A5X1"
    }
  ],
  "amount_money": {
    "amount": 200,
    "currency": "USD"
  },
  "billing_address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "administrative_district_level_1": "NY",
    "country": "US",
    "locality": "New York",
    "postal_code": "10003"
  },
  "card_nonce": "card_nonce_from_square_123",
  "delay_capture": false,
  "idempotency_key": "74ae1696-b1e3-4328-af6d-f1e04d947a13",
  "note": "some optional note",
  "reference_id": "some optional reference id",
  "shipping_address": {
    "address_line_1": "123 Main St",
    "administrative_district_level_1": "CA",
    "country": "US",
    "locality": "San Francisco",
    "postal_code": "94114"
  },
  "customer_card_id": "customer_card_id0"
}
```

Back