Square Gift Card Payments
This topic shows you how to add Square Gift Cards to an existing payment form integration. The integration requires additional payment form code in your web client and Square API calling code in your backend.
On this page
Buyers submit Square Gift Cards by entering only a card number. Expiration dates, CVV numbers, and postal codes are not used. Accordingly, the payment form for Gift Cards only has a card number field. The nonce generated from a Gift Card is used as the
.source_id value and a payment is created as though the source is any other payment card.
Did you know?
Gift Cards are configured and sold by a seller using the Seller Dashboard and can only be used to pay for purchases from the seller who issued the Gift Card.
Some payment integrations allow for multiple payments on a purchase while others do not. Gift Card payments must take this into account. For example, an integration might disallow 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 integration 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 USD 200 and the Gift Card balance is USD 50. In this case, the Gift Card payment is authorized the full card balance. The remaining purchase amount of USD 150 is covered by another Gift Card or payment card, creating an additional
The calculation of the remaining purchase amounts and linking of individual payments is handled by the payment integration backend and is normally done 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.
Approved Gift Card funds are held until the purchase is complete or canceled, or the approval times out in 7 days. Be sure to complete the payment cancel flow if the buyer decides not to complete a purchase.
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 payment card mode for accepting credit or debit card payments.
To support these payment methods, create the following:
Client. A payment form page to render the gift card form, payment card form, and optional digital wallets.
Server. An endpoint to create a
Paymentfor each posted nonce. Optionally, the endpoint can request the
Ordercreated by the checkout for linking the payments and order completion.
Any combination of Gift Card and payment card can be used to pay the total due in a purchase. When a Gift Card balance is not 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 nonces indIvidually and associates all payments with the
Order representing a purchase.
Did you know?
Order is used to associate multiple payments, a single transaction is shown in the Seller Dashboard with a payment for each card used by the buyer.
If more than one
Payment is created without a parent
Order, the purchase can still be completed but the Seller Dashboard shows a separate transaction for each payment.
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
The payment page gets the
.idfrom the checkout page.
The buyer provides a payment in Gift Card or payment card form to generate a payment nonce.
Client: POSTs the payment nonce and the
Gets the unpaid balance of the order from the checkout service.
Uses the nonce to create a
Paymentusing the unpaid balance and then POSTs the
Sends a 200 response to the client with the
.id, the remaining order balance (which might be zero), and the payment status.
If the response payment status is
APPROVEDand the remaining order amount is greater than zero, the client collects another payment (step 2).
If the response payment status is
COMPLETED, the purchase 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: