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.

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

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

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

    ...   
   "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 Redeem a gift card when using the Payments API.

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.

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.

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.

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.

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

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.

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

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

In this example, do the following:

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

   Create customer

   cURL

   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 Payment tokens for testing the Payments API.

   Create card

   cURL

   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

   cURL

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

• Delayed Capture of a Card Payment
• Partial Payment Authorizations
• Card Payment and Statement Description