Learn how to provide cards (credit, debit, and square gift card) as a payment source in a Payments API CreatePayment request.
Payments API

Take Card Payments

You can charge a card (credit/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 Balance of the account.

Important

You cannot use the payment card details provided by a buyer in the CreatePayment endpoint. Instead, you need to use one of the Square client-side libraries for web and mobile applications 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.

Link to section
Overview

Do not 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, one-time-use payment token. For more information, see Online Payment Options 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-01-19' \
  -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 does not verify that the card they are trying to use is going to be accepted by the bank. The card may 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, 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 on process completion.

Link to section
APPROVED

If the CreatePayment request is for authorization only, it is a delayed capture. The card is valid and the amount is authorized by the cardholder's bank. Funds are guaranteed and the seller receives them 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 are not credited to the seller's Square balance when the Payment.status is one of the following:

  • FAILED. The payment request is declined.

  • CANCELED. The card payment is voided and the funds are released.

Note

For cash or external payments, this status has no impact because Square is not 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 Payments API endpoint testing.

  • Provide a Sandbox access token to authenticate your request in the Authorization header. For more information, see Make an API Request.

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-01-19' \
  -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"
  }'
Try in API Explorer

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 fragment, 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 do not 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).

Did you know?

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).

  1. 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-01-19' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "family_name": "Doe",
    "given_name": "John"
  }'
    Try in API Explorer

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

  2. 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 Payments API endpoint testing.

    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-01-19' \
  -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"
    }
  }'
    Try in API Explorer

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

  3. 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-01-19' \
  -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}"
  }'
    Try in API Explorer

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

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

Did you know?

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

The following topics provide additional information:

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

On this page