Create payment
Charges a payment source (for example, a card represented by customer's card on file or a card nonce).
In addition to the payment source, the request must include the amount to accept for the payment.
There are several optional parameters that you can include in the request (for example, tip money, whether to autocomplete the payment, or a reference ID to correlate this payment with another system).
The PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS
OAuth permission is required
to enable application fees.
Name | Description |
---|---|
source_
Required
|
The ID for the source of funds for this payment. This can be a nonce generated by the Square payment form or a card on file made with the Customers API. |
idempotency_
Required
|
A unique string that identifies this Max: 45 characters Note: The number of allowed characters might be less than the stated maximum, if multi-byte characters are used. For more information, see Idempotency. |
amount_
Required
|
The amount of money to accept for this payment, not including The amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see Working with Monetary Amounts. The currency code must match the currency associated with the business that is accepting the payment. |
tip_
Beta
|
The amount designated as a tip, in addition to The amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see Working with Monetary Amounts. The currency code must match the currency associated with the business that is accepting the payment. |
app_
|
The amount of money that the developer is taking as a fee for facilitating the payment on behalf of the seller. The amount cannot be more than 90% of the total amount of the payment. The amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see Working with Monetary Amounts. The fee currency code must match the currency associated with the seller that is accepting the payment. The application must be from a developer account in the same country and using the same currency code as the seller. For more information about the application fee scenario, see Take Payments and Collect Fees. |
delay_
Beta
|
The duration of time after the payment's creation when Square automatically cancels the
payment. This automatic cancellation applies only to payments that do not reach a terminal state
(COMPLETED, CANCELED, or FAILED) before the This parameter should be specified as a time duration, in RFC 3339 format, with a minimum value of 1 minute. Note: This feature is only supported for card payments. This parameter can only be set for a delayed
capture payment ( Default:
Example for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S |
autocomplete
|
If set to Default: true |
order_
|
Associates a previously created order with this payment. |
customer_
|
The Customer ID of the customer associated with the payment. This is required if the |
location_
|
The location ID to associate with the payment. If not specified, the default location is used. |
reference_
|
A user-defined ID to associate with the payment. You can use this field to associate the payment to an entity in an external system (for example, you might specify an order ID that is generated by a third-party shopping cart). Limit 40 characters. |
verification_
|
An identifying token generated by For more information, see SCA Overview. |
accept_
Beta
|
If set to For more information, see Partial amount with Square Gift Cards. Default: false |
buyer_
|
The buyer's email address. |
billing_
|
The buyer's billing address. |
shipping_
|
The buyer's shipping address. |
note
|
An optional note to be entered by the developer when creating a payment. Limit 500 characters. |
statement_
Beta
|
Optional additional payment information to include on the customer's card statement as part of the statement description. This can be, for example, an invoice number, ticket number, or short description that uniquely identifies the purchase. Note that the |
Response Fields
Name | Description |
---|---|
errors
|
Information about errors encountered during the request. |
payment
|
The newly created payment. |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.com/v2/payments \
-X POST \
-H 'Square-Version: 2021-02-26' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"idempotency_key": "4935a656-a929-4792-b97c-8848be85c27c",
"amount_money": {
"amount": 200,
"currency": "USD"
},
"source_id": "ccof:uIbfJXhXETSP197M3GB",
"autocomplete": true,
"customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8",
"location_id": "XK3DBG77NJBFX",
"reference_id": "123456",
"note": "Brief description",
"app_fee_money": {
"amount": 10,
"currency": "USD"
}
}'
{
"payment": {
"id": "GQTFp1ZlXdpoW4o6eGiZhbjosiDFf",
"created_at": "2019-07-10T13:23:49.154Z",
"updated_at": "2019-07-10T13:23:49.446Z",
"amount_money": {
"amount": 200,
"currency": "USD"
},
"app_fee_money": {
"amount": 10,
"currency": "USD"
},
"total_money": {
"amount": 200,
"currency": "USD"
},
"status": "COMPLETED",
"source_type": "CARD",
"card_details": {
"status": "CAPTURED",
"card": {
"card_brand": "VISA",
"last_4": "1111",
"exp_month": 7,
"exp_year": 2026,
"fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw",
"card_type": "DEBIT",
"prepaid_type": "PREPAID",
"bin": "411111"
},
"entry_method": "ON_FILE",
"cvv_status": "CVV_ACCEPTED",
"avs_status": "AVS_ACCEPTED",
"auth_result_code": "nsAyY2",
"statement_description": "SQ *MY MERCHANT",
"card_payment_timeline": {
"authorized_at": "2019-07-10T13:23:49.234Z",
"captured_at": "2019-07-10T13:23:49.446Z"
}
},
"location_id": "XTI0H92143A39",
"order_id": "m2Hr8Hk8A3CTyQQ1k4ynExg92tO3",
"reference_id": "123456",
"note": "Brief description",
"customer_id": "RDX9Z4XTIZR7MRZJUXNY9HUK6I",
"receipt_number": "GQTF",
"receipt_url": "https://squareup.com/receipt/preview/GQTFp1ZlXdpoW4o6eGiZhbjosiDFf"
}
}
Error Descriptions
400 Bad request |
ADDRESS_ The card issuer declined the request because the postal code is invalid. |
> |
400 Bad request |
CARDHOLDER_ The card issuer has declined the transaction due to restrictions on where the card can be used. For example, a gift card is limited to a single merchant. |
> |
400 Bad request |
CARD_ The card issuer declined the request because the card is expired. |
> |
400 Bad request |
CARD_ The card is not supported either in the geographic region or by the MCC merchant category code |
> |
400 Bad request |
CARD_ The provided card token (nonce) has expired. |
> |
400 Bad request |
CARD_ The provided card token (nonce) was already used to process payment. |
> |
400 Bad request |
CVV_ The card issuer declined the request because the CVV value is invalid. |
> |
400 Bad request |
EXPIRATION_ The card expiration date is either invalid or indicates that the card is expired. |
> |
400 Bad request |
GENERIC_ Square received a decline from the cardholder's bank without any additional information. If the card information seems correct, the card holder can contact their card issuer to ask for more information. |
> |
400 Bad request |
GIFT_ When a Gift Card is a payment source, you can allow taking a partial payment
by adding the |
> |
400 Bad request |
INSUFFICIENT_ The funding source has insufficient funds to cover the payment. |
> |
400 Bad request |
INSUFFICIENT_ The Square account does not have the permissions to accept this payment. For example, Square may limit which merchants are allowed to receive gift card payments. |
> |
400 Bad request |
INVALID_ The card issuer was not able to locate account on record. |
> |
400 Bad request |
INVALID_ The credit card cannot be validated based on the provided details. |
> |
400 Bad request |
INVALID_ Generic error - the provided card data is invalid. |
> |
400 Bad request |
INVALID_ The provided email address is invalid. |
> |
400 Bad request |
INVALID_ The expiration date for the payment card is invalid. For example, it indicates a date in the past. |
> |
400 Bad request |
INVALID_ The appfeemoney on a payment is too high. |
> |
400 Bad request |
INVALID_ The Square account cannot take payments in the specified region. A Square account can take payments only from the region where the account was created. |
> |
400 Bad request |
INVALID_ The card issuer declined the request because the PIN is invalid. |
> |
400 Bad request |
INVALID_ The postal code is incorrectly formatted. |
> |
400 Bad request |
MANUALLY_ The card must be swiped, tapped, or dipped. Payments attempted by manually entering the card number are declined. |
> |
400 Bad request |
PAN_ The specified card number is invalid. For example, it is of incorrect length or is incorrectly formatted. |
> |
400 Bad request |
PAYMENT_ Square declined the request because the payment amount exceeded the processing limit for this merchant. |
> |
400 Bad request |
TRANSACTION_ The card issuer has determined the payment amount is either too high or too low. The API returns the error code mostly for credit cards (for example, the card reached the credit limit). However, sometimes the issuer bank can indicate the error for debit or prepaid cards (for example, card has insufficient funds). |
> |
400 Bad request |
VOICE_ The card issuer declined the request because the issuer requires voice authorization from the cardholder. |
> |
402 Payment required |
ALLOWABLE_ The card has exhausted its available pin entry retries set by the card issuer. Resolving the error typically requires the card holder to contact the card issuer. |
> |
402 Payment required |
BAD_ The card expiration date is either missing or incorrectly formatted. |
> |
402 Payment required |
CHIP_ The card issuer requires that the card be read using a chip reader. |
> |
403 Forbidden |
CARD_ The location provided in the API call is not enabled for credit card processing. |
> |
503 Service unavailable |
TEMPORARY_ A temporary internal error occurred. You can safely retry your call using the same idempotency key. |
> |
{
"errors": [
{
"code": "ADDRESS_VERIFICATION_FAILURE",
"category": "PAYMENT_METHOD_ERROR"
}
]
}