Payments API

Card Payments

You can charge a card (a credit card, debit card, or Square gift card) using the CreatePayment endpoint. When the request is received, Square charges the specified card and deposits the funds in the Square account.

You can't use the payment card details provided by a buyer in the CreatePayment endpoint. Instead, you need to use the Web Payments SDK for the web or In-App Payments SDK for mobile to collect the card details. These libraries return a payment token for use with CreatePayment.

As part of processing the card payment, Square takes care of maintaining PCI compliance, detecting fraud, and managing disputes.

Overview
Payment status
Examples
Related topics

Link to section
Overview

Don't specify card information (card number, expiration date, and other information) directly in a CreatePayment call. Instead, provide one of the following in the request:

Payment token. Square provides client libraries that developers use to collect payment information in web or mobile applications. These libraries take the payment information buyers provide in the client UI and generate a secure single-use payment token. For more information, see Online Payment Solutions and In-App Payments SDK Overview.
These clients depend on a server component that sends CreatePayment requests to Square for processing the payment with the token. In the payment request, the server provides the payment token as the value of the source_id. The following is an example CreatePayment request that directs Square to charge $20 to the payment token specified as source_id:
Create Payment
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
```
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "source_id": "{PAYMENT_TOKEN_REPRESENTING_A_PAYMENT_SOURCE}"
  }'
```
Try in API Explorer
Note

If your client application has implemented 3-D Secure to verify the identity of the buyer, a verification token is returned along with the payment token. This verification token assures the card-issuing bank that the buyer is who they say they are. It doesn't verify that the card they are trying to use is going to be accepted by the bank. The card might still be declined. This is why you can still get payment errors, some of which indicate card declines.
Card on file. A seller can store customer profiles in the seller's Customer Directory and then add a card on file for the customer.
Applications can later charge the card on file by setting the card ID as the source_id value in a CreatePayment request. In this case, the customer_id is also required in the request.
- 1
- 2
- 3
- 4
```
  ...   
 "source_id": "{CARD_ON_FILE_ID}",
  "customer_id": "{CUSTOMER_ID}"
  ...
```
Square gift card on file. Applications can specify the ID of a Square gift card as a source_id in a CreatePayment request. For more information, see Use a gift card as a payment source in the Payments API.

Link to section
Payment status

After your application calls CreatePayment, Square attempts to get the requested funds. If the issuing bank rejects the request, the status is FAILED. Otherwise, the status is one of the following.

Link to section
COMPLETED

If the CreatePayment request is for authorization and capture, the payment is processed immediately. The process to capture the funds with the cardholder's bank is initiated. The funds are guaranteed and the seller receives the funds when the process is complete.

Link to section
APPROVED

If the CreatePayment request is for authorization only, it's a delayed capture. The card is valid and the amount is authorized by the cardholder's bank. The funds are guaranteed and the seller receives the funds when the payment is captured (see CompletePayment). Take one of the following actions on an APPROVED payment:

Capture the payment by calling CompletePayment.
Cancel the payment by calling CancelPayment.

Link to section
FAILED or CANCELED

Funds aren't credited to the seller's Square account when the Payment.status is one of the following:

FAILED. The payment request is declined.
CANCELED. The payment is voided and the funds are released.

For cash or external payments, this status has no impact because Square isn't involved in any funds movement (the seller already has the funds).

Link to section
Examples

The following are examples of CreatePayment requests that you can test in the Square Sandbox and review the resulting Payment objects.

Link to section
Payment token as a payment source

To test CreatePayment calls in the Square Sandbox:

Specify the Square-provided fake payment token (for example, cnon:card-nonce-ok) as source_id. For more information, see Payment tokens for testing the Payments API.
Provide a Sandbox access token to authenticate your request in the Authorization header. For more information, see Make your First API Call.

You can then run the following cURL CreatePayment request. Note that the request specifies the Square Sandbox domain (connect.squareupsandbox.com) as the endpoint URL.

Create Payment

1
2
3
4
5
6
7
8
9
10
11
12
13

curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 2000,
      "currency": "USD"
    },
    "source_id": "cnon:card-nonce-ok"
  }'

In response, the endpoint return a Payment object as shown:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

{
   "payment":{
      "id":"Zg81uQkAcCh1aJMAPymUzilP4ADZY",
      "created_at":"2021-12-22T03:54:17.125Z",
      "updated_at":"2021-12-22T03:54:17.319Z",
      "amount_money":{
         "amount":2000,
         "currency":"USD"
      },
      "status":"COMPLETED",
      "delay_duration":"PT168H",
      "source_type":"CARD",
      "card_details":{
         "status":"CAPTURED",
         "card":{
            "card_brand":"VISA",
            "last_4":"5858",
            "exp_month":12,
            "exp_year":2023,
            "fingerprint":"sq-1-INCyQnSb8QOHkoFASh566s5S-jwk6IPaJes7jREW-Zyprrx0smmoNP_J2zwL6j-1OA",
            "card_type":"CREDIT",
            "prepaid_type":"NOT_PREPAID",
            "bin":"453275"
         },
         "entry_method":"KEYED",
         "cvv_status":"CVV_ACCEPTED",
         "avs_status":"AVS_ACCEPTED",
         "statement_description":"SQ *DEFAULT TEST ACCOUNT",
         "card_payment_timeline":{
            "authorized_at":"2021-12-22T03:54:17.234Z",
            "captured_at":"2021-12-22T03:54:17.320Z"
         }
      },
      "location_id":"S8GWD5R9QB376",
      "order_id":"SsTiD94XDwpPPjVDPt2be8w9U47YY",
...
   }
}

In the preceding Payment object example, note the following:

The payment status in the response is COMPLETED, which indicates that the payment source is successfully charged.
order_id refers to the order that the payment is associated with. For compatibility with other products (for example, the Point of Sale application), all payments taken for a Square seller need an order. If you don't supply one, the Payments API creates and maintains one automatically.
The payment token in the request represents a Sandbox VISA card (see the card_details.card.card_brand field value).

You can also use a Square gift card as a payment source. For more information, see Use a gift card as a payment source in the Payments API.

Link to section
Card on file as a payment source

In this example, do the following:

Create a customer profile using the CreateCustomer endpoint (Customers API).
Create a card on file using the CreateCard endpoint (Cards API).
Charge the card on file using CreatePayment endpoint (Payments API).

Send a CreateCustomer request to create a customer. Make sure to update the command and provide the Sandbox access token.

Create Customer

1
2
3
4
5
6
7
8
9
10

curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "family_name": "Doe",
    "given_name": "John"
  }'

Copy the id from the response. You use this value as the customer_id in the next step.

Send a CreateCard request to add a card on file. This example uses the Square-provided payment token (cnon:card-nonce-ok) to add a card on file. In a production environment, your application generates a payment token using the card information that customers provide.

For more information about adding a gift card on file, see Payment tokens for testing the Payments API.

Create Card

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

curl https://connect.squareupsandbox.com/v2/cards \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "source_id": "cnon:card-nonce-ok",
    "card": {
      "billing_address": {
        "address_line_1": "500 Electric Ave",
        "address_line_2": "Suite 600",
        "locality": "New York",
        "administrative_district_level_1": "NY",
        "postal_code": "94103",
        "country": "US"
      },
      "cardholder_name": "John Doe",
      "customer_id": "{CUSTOMER_ID}",
      "reference_id": "alternate-id-1"
    }
  }'

This creates a card on file. You need the id of the card on file to take a payment.

Send a CreatePayment request to charge the card on file. This example charges $20 to the card on file. Make sure to update the request by providing the ID of the card on file as source_id and the customer_id.

Create Payment

1
2
3
4
5
6
7
8
9
10
11
12
13
14

curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 2000,
      "currency": "USD"
    },
    "source_id": "{CARD_ON_FILE_ID}",
    "customer_id": "{CUSTOMER_ID}"
  }'

After processing the payment, the endpoint returns the resulting Payment object.

Verify the transaction in the Sandbox Seller Dashboard. For more information, see Verify the Payment.

A seller can use the Square Point of Sale application and Seller Dashboard to create customers and add a card on file. To test this experience, see Use Card on File with the Square Point of Sale App.

Link to section
Related topics

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Card Payments

Important

On this page

Link to section
Overview

Note

Link to section
Payment status

Link to section
COMPLETED

Link to section
APPROVED

Link to section
FAILED or CANCELED

Note

Link to section
Examples

Link to section
Payment token as a payment source

Did you know?

Link to section
Card on file as a payment source

Did you know?

Link to section
Related topics

On this page

Docs

Card Payments

Important

On this page

Link to section Overview

Note

Link to section Payment status

Link to section COMPLETED

Link to section APPROVED

Link to section FAILED or CANCELED

Note

Link to section Examples

Link to section Payment token as a payment source

Did you know?

Link to section Card on file as a payment source

Did you know?

Link to section Related topics

On this page

Link to section
Overview

Link to section
Payment status

Link to section
COMPLETED

Link to section
APPROVED

Link to section
FAILED or CANCELED

Link to section
Examples

Link to section
Payment token as a payment source

Link to section
Card on file as a payment source

Link to section
Related topics