Applies to: Web Payments SDK | Gift Cards API | Payments API | Orders API
Learn how to process partial payments with Square Gift Cards, the Web Payments SDK, and other APIs.
A Square gift card is a digital or physical card that customers can use as payment at a specific Square seller's store. You can create these gift cards using the Gift Cards API or directly from the Square Dashboard. The following steps detail how to authorize a Square gift card for a partial payment. The example code was written to complement the Web Payments Quickstart, so you might find it useful to consult the example repository.
- You've created a Square account and application.
- You've installed the client-side SDK of your choice (Web Payments SDK, In-App Payments SDK - iOS, or In-App Payments SDK - Android).
- There is at least one item in the seller's catalog.
- To test the example code, you can find your production personal access token, application ID, and location ID in the Developer Console.
- Your application has
GIFT_CARDS_READandGIFT_CARDS_WRITEpermissions. - You used the Gift Cards API and Gift Card Activities API or the Square Dashboard to create an active gift card with an initial balance.
- It's only possible to add a tip to a gift card payment if the gift card balance is sufficient to pay the order amount and tip amount combined. Otherwise, Square returns an
INSUFFICIENT_FUNDSerror.
Note
The following client-side sample code uses the Web Payments SDK, but the high-level flow is similar for mobile applications. For mobile-specific code, see Gift Card Payments for the In-App Payments SDK.
When a customer finishes adding items to their cart and proceeds to check out on the client, pass their selections to your server so that you can send a CreateOrder request. In addition to an access token and an idempotency_key, you need to pass an Order object with the following information in the request body:
location_id- A unique identifier for the physical place of business that fulfills the order. For testing the example code, you can find locations that your application has access to in the Developer Console. In production, send a request to ListLocations.customer_id- A unique identifier for the customer that was returned in a request to CreateCustomer.line_items- An array of information about the products that the customer is purchasing, as they relate to the catalog. For more information about how to create more complex orders, see Create Orders.
The following example CreateOrder request creates an Order for a small coffee. In the corresponding example catalog, a small coffee has the catalog_object_id of U2LA7CNNKPXMMSBVDY4JCZOO.
Create order
Store the returned Order id. You need it to create payments in the following steps.
To test the example code, securely store your developer access token, located in the Square Developer Console, according to your application logic (which could be something like a .env).
Warning
Don't deploy an application into production that contains your personal access token. For a secure authorization implementation in production, implement OAuth instead of using a personal access token. For more information about using OAuth with Square, see OAuth API.
Add the following script to the <head> of your .html to initialize the Web Payments SDK:
<head>
<script
type="text/javascript"
src="https://web.squarecdn.com/v1/square.js"
></script>
</head>To initialize the Square Payments object, pass your application ID and location ID, also found in the Developer Console, to Square.payments.
const payments = Square.payments(APPLICATION_ID, LOCATION_ID);Write an initializeGiftCard function to call payments.giftCard() to create a GiftCard object and attach the GiftCard to a DOM element.
async function initializeGiftCard(payments) {
const giftCard = await payments.giftCard();
await giftCard.attach('#gift-card-container');
return giftCard;
}Add an event listener to execute initializeGiftCard when the DOM loads.
document.addEventListener('DOMContentLoaded', async function () {
let giftCard;
try {
giftCard = await initializeGiftCard(payments);
} catch (e) {
console.error('Initializing Gift Card failed', e);
return;
}
// Placeholder for handlePaymentMethodSubmission
});This displays a gift card input field to the customer.
To generate a corresponding token from the customer's input, you need to call the SDK tokenize() method. The following example calls the method within a helper tokenize function:
async function tokenize(paymentMethod) {
const tokenResult = await paymentMethod.tokenize();
if (tokenResult.status === 'OK') {
return tokenResult.token;
} else {
let errorMessage = `Tokenization failed with status: ${tokenResult.status}`;
if (tokenResult.errors) {
errorMessage += ` and errors: ${JSON.stringify(
tokenResult.errors,
)}`;
}
throw new Error(errorMessage);
}
}Add the helper tokenize function to a parent handler function that's called when a customer submits a payment. For example, the following event listener fires the handler handlePaymentMethodSubmission after the customer inputs the gift card number and clicks the Pay with Gift Card button:
const giftCardButton = document.getElementById('gift-card-button');
giftCardButton.addEventListener('click', async function (event) {
await handlePaymentMethodSubmission(event, giftCard);
});handlePaymentMethodSubmission then calls tokenize, and passes the token result to a helper function, called createPayment in this example.
async function handlePaymentMethodSubmission(event, paymentMethod) {
try {
const token = await tokenize(paymentMethod);
const paymentResults = await createPayment(token);
} catch (e) {
console.error(e.message);
}
}createPayment is a function that you write to pass the token and other data from the client to your server, so that you can make the backend call to CreatePayment. You need to pass the following information:
source_id- The token generated for the gift card when you called the Squaretokenizemethod. For the purposes of this example, imagine that thesource_idcorresponds to a gift card with a $1 value.order_id- The ID for theOrderobject that you created in step 1.
In addition to the source_id, the order_id, and an idempotency_key, you need to set the following fields in the CreatePayment request body:
accept_partial_authorization- Must betrueto create a gift card payment, in case there's an outstanding balance after the gift card is applied. Iffalse, Square returns anINSUFFICIENT_FUNDSerror.autocomplete- Must befalse. If there's an outstanding balance, additional payments need to be created and added to the order.amount_money- The payment amount.
In the following example, the order_id corresponds to an order for one small coffee, with a total_money value of 300. The source_id corresponds to a $1.00 gift card. The amount_money charges the entire amount owed to the gift card, even though that amount exceeds the card balance.
Create payment
In this example, the gift card only has a $1 balance, so a $1 Payment is created. The Payment.amount_money value is 100.
Subtract Payment.amount_money from Order.net_amount_money_due to calculate the outstanding balance. In this example, 300 – 100 = 200 is the outstanding balance.
Prompt the customer to add an additional payment method in the way that best suits your application interface and logic. Then, repeat the steps that you followed to collect the first gift card payment: after the customer submits their input, generate a token for the payment method and call CreatePayment from your server.
This time, set the amount_money to the outstanding balance of 200.
Create payment
When the outstanding balance is 0, call PayOrder from your server to complete the customer’s purchase. Trigger this call according to your application interface and logic. For example, you could send the request after a customer selects "Submit Order."
The endpoint takes the order_id as a path param: /orders/order_id/pay. In the body of the request, pass the payment_ids associated with the Order in addition to auth credentials and an idempotency_key, as in the following example.
Pay order
At this point, the customer has paid for the order and the order is visible in the Square Dashboard Order Manager.
Display a success message according to your application interface and logic.