Card Payments

Applies to: Payments API | Web Payments SDK | In-App Payments SDK

Learn how to provide a card as a payment source.

Link to section

Overview

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.

Note

You cannot 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.

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.

    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

    Note

    If your client application has implemented Strong Customer Authentication 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.

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.

Note

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:

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

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

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

Did you know?

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

Link to section

Card on file as a payment source

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

    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

    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

    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.

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

See also