Square Gift Card Payments with the Web Payments SDK

Applies to: Web Payments SDK | Gift Cards API | Payments API | Orders API

Learn about taking Square gift card payments with the Web Payments SDK.

You can build applications with the Web Payments SDK that take payments from a Square gift card. A Square gift card enables sellers to boost sales and attract new customers. Sellers can launch a complete gifting program with digital gift cards, which can be purchased online. Buyers can choose to send digital cards to friends and family and introduce them to the seller's business.

To make purchases, buyers submit Square gift cards by entering only a card number. Expiration dates, CVV numbers, and postal codes aren't used. Accordingly, the payment form for gift cards only has a card number field. The payment token generated from a gift card is used as the Payment .source_id value and a payment is created as though the source is any other payment card.

Some payment applications allow for multiple payments on a purchase while others don't. Gift card payments must take this into account. For example, an application might not allow a gift card payment if it cannot cover the entire purchase amount. An application can restrict gift card payment approvals based on the available balance of a gift card. The approval restriction is set on individual payment requests.

If an application allows multiple payments for a purchase, it should allow for partial authorization approval when the gift card balance is less than the total purchase amount. In this case, the full balance of the card is used in the purchase, leaving a remaining purchase amount. This approval is known as partial authorization.

For example, a buyer is purchasing a pair of running shoes for $200 USD and the gift card balance is $50 USD. In this case, the gift card payment is authorized for the full card balance. The remaining purchase amount of $150 USD is covered by another gift card or payment card, creating an additional Payment object.

The calculation of the remaining purchase amount and linking of individual payments is handled by the payment application's backend and is normally performed in the server session that manages the checkout experience.

A buyer might decide to cancel a purchase after a gift card payment is approved and before completing a checkout. Canceling a purchase with a gift card involves calling Payments.CancelPayment.

This call flow assumes that your backend provides checkout and payment pages. To accept a gift card, a payment page renders the payment form in a gift card mode that only has a gift card number input field. The payment page should also render a payment form in the payment card mode for accepting credit or debit card payments.

To support these payment methods, create the following:

• Client - A payment method application to render the gift card form, payment card form, and optional digital wallets.
• Server - An endpoint to create a Payment object for each posted payment token. Optionally, the endpoint can request the Order object created by the checkout for linking the payments and order completion.

Any combination of a gift card and payment card can be used to pay the total purchase amount. When a gift card balance isn't enough to complete a purchase, a buyer makes an additional payment to complete the purchase. The payment can be another gift card or a payment card.

This flow processes payment tokens individually and associates all payments with the Order representing a purchase.

The following call flow supports a multiple payment purchase:

Client: The checkout page requests a new Order for the purchase from the server.

Server: Calls the Orders API to create an order and respond to the client with the new Order .id.

Client:

1. The payment page gets the Order .id from the checkout page.
2. The buyer provides a payment in a gift card or payment card form to generate a payment token.

Client: POSTs the payment token and the Order .id.

Server:

1. Gets the unpaid balance of the order from the checkout service.
2. Uses the payment token to create a Payment using the unpaid balance and then POSTs the Payment to the Order.
3. Sends a 200 response to the client with the Order .id, the remaining order balance (which might be zero), and the payment status.

Client:

1. If the response payment status is APPROVED and the remaining order amount is greater than zero, the client collects another payment.
2. If the response payment status is COMPLETED, the purchase gift card flow is complete.

The following diagram shows the flow when a buyer makes a purchase with a gift card and then pays the remaining balance with a payment card:

To support gift card payments, use the Gift Cards API and integrate it into your application. The following video introduces the Gift Cards API and demonstrates its features. The Gift Cards API provides endpoints for creating a gift card, retrieving gift card information, linking a customer to a gift card, and unlinking a customer from a gift card.

• Take a Gift Card Payment
• Partial Payments with Square Gift Cards