charge-request.md

Charge Request

Defines the parameters that can be included in the body of a request to the Charge endpoint.

Deprecated - recommend using CreatePayment

Structure

Charge Request

Fields

Name	Type	Tags	Description
idempotency_key	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 for more information. Constraints: Minimum Length: 1, Maximum Length: 192
amount_money	Money	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 for more information.
card_nonce	string	Optional	A payment token generated from the 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
customer_card_id	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
delay_capture	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 endpoint) or a Void (with the VoidTransaction endpoint). Default value: false
reference_id	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
note	string	Optional	An optional note to associate with the transaction. This value cannot exceed 60 characters. Constraints: Maximum Length: 60
customer_id	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
billing_address	Address	Optional	Represents a physical address.
shipping_address	Address	Optional	Represents a physical address.
buyer_email_address	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.
order_id	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
additional_recipients	List of Charge Request Additional Recipient	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.
verification_token	string	Optional	A token generated by SqPaymentForm's verifyBuyer() that represents customer's device info and 3ds challenge result.

Example (as 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"
  }
}