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.
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
:
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 aCreatePayment
request. In this case, thecustomer_id
is also required in the request.Square gift card on file. Applications can specify the ID of a Square gift card as a
source_id
in aCreatePayment
request. For more information, see Use a gift card as a payment source in 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, 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 on process completion.
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
.
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).
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
) assource_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.
In response, the endpoint return a Payment object as shown:
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.
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.Copy the
id
from the response. You use this value as thecustomer_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 Payments API endpoint testing.
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 assource_id
and thecustomer_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 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.
The following topics provide additional information:
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.