gift-cards.md

Gift Cards

GiftCardsApi giftCardsApi = client.getGiftCardsApi();

Class Name

GiftCardsApi

Methods

• List Gift Cards
• Create Gift Card
• Retrieve Gift Card From GAN
• Retrieve Gift Card From Nonce
• Link Customer to Gift Card
• Unlink Customer From Gift Card
• Retrieve Gift Card

List Gift Cards

Lists all gift cards. You can specify optional filters to retrieve a subset of the gift cards. Results are sorted by created_at in ascending order.

CompletableFuture<ListGiftCardsResponse> listGiftCardsAsync(
    final String type,
    final String state,
    final Integer limit,
    final String cursor,
    final String customerId)

Parameters

Parameter	Type	Tags	Description
type	String	Query, Optional	If a type is provided, the endpoint returns gift cards of the specified type. Otherwise, the endpoint returns gift cards of all types.
state	String	Query, Optional	If a state is provided, the endpoint returns the gift cards in the specified state. Otherwise, the endpoint returns the gift cards of all states.
limit	Integer	Query, Optional	If a limit is provided, the endpoint returns only the specified number of results per page. The maximum value is 200. The default value is 30. For more information, see Pagination.
cursor	String	Query, Optional	A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see Pagination.
customerId	String	Query, Optional	If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer.

Response Type

ListGiftCardsResponse

Example Usage

giftCardsApi.listGiftCardsAsync(null, null, null, null, null).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Create Gift Card

Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card has a PENDING state. To activate a gift card so that it can be redeemed for purchases, call CreateGiftCardActivity and create an ACTIVATE activity with the initial balance. Alternatively, you can use RefundPayment to refund a payment to the new gift card.

CompletableFuture<CreateGiftCardResponse> createGiftCardAsync(
    final CreateGiftCardRequest body)

Parameters

Parameter	Type	Tags	Description
body	CreateGiftCardRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

CreateGiftCardResponse

Example Usage

CreateGiftCardRequest body = new CreateGiftCardRequest.Builder(
    "NC9Tm69EjbjtConu",
    "81FN9BNFZTKS4",
    new GiftCard.Builder(
        "DIGITAL"
    )
    .build()
)
.build();

giftCardsApi.createGiftCardAsync(body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Retrieve Gift Card From GAN

Retrieves a gift card using the gift card account number (GAN).

CompletableFuture<RetrieveGiftCardFromGANResponse> retrieveGiftCardFromGANAsync(
    final RetrieveGiftCardFromGANRequest body)

Parameters

Parameter	Type	Tags	Description
body	RetrieveGiftCardFromGANRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

RetrieveGiftCardFromGANResponse

Example Usage

RetrieveGiftCardFromGANRequest body = new RetrieveGiftCardFromGANRequest.Builder(
    "7783320001001635"
)
.build();

giftCardsApi.retrieveGiftCardFromGANAsync(body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Retrieve Gift Card From Nonce

Retrieves a gift card using a secure payment token that represents the gift card.

CompletableFuture<RetrieveGiftCardFromNonceResponse> retrieveGiftCardFromNonceAsync(
    final RetrieveGiftCardFromNonceRequest body)

Parameters

Parameter	Type	Tags	Description
body	RetrieveGiftCardFromNonceRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

RetrieveGiftCardFromNonceResponse

Example Usage

RetrieveGiftCardFromNonceRequest body = new RetrieveGiftCardFromNonceRequest.Builder(
    "cnon:7783322135245171"
)
.build();

giftCardsApi.retrieveGiftCardFromNonceAsync(body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Link Customer to Gift Card

Links a customer to a gift card, which is also referred to as adding a card on file.

CompletableFuture<LinkCustomerToGiftCardResponse> linkCustomerToGiftCardAsync(
    final String giftCardId,
    final LinkCustomerToGiftCardRequest body)

Parameters

Parameter	Type	Tags	Description
giftCardId	String	Template, Required	The ID of the gift card to be linked.
body	LinkCustomerToGiftCardRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

LinkCustomerToGiftCardResponse

Example Usage

String giftCardId = "gift_card_id8";
LinkCustomerToGiftCardRequest body = new LinkCustomerToGiftCardRequest.Builder(
    "GKY0FZ3V717AH8Q2D821PNT2ZW"
)
.build();

giftCardsApi.linkCustomerToGiftCardAsync(giftCardId, body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Unlink Customer From Gift Card

Unlinks a customer from a gift card, which is also referred to as removing a card on file.

CompletableFuture<UnlinkCustomerFromGiftCardResponse> unlinkCustomerFromGiftCardAsync(
    final String giftCardId,
    final UnlinkCustomerFromGiftCardRequest body)

Parameters

Parameter	Type	Tags	Description
giftCardId	String	Template, Required	The ID of the gift card to be unlinked.
body	UnlinkCustomerFromGiftCardRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

UnlinkCustomerFromGiftCardResponse

Example Usage

String giftCardId = "gift_card_id8";
UnlinkCustomerFromGiftCardRequest body = new UnlinkCustomerFromGiftCardRequest.Builder(
    "GKY0FZ3V717AH8Q2D821PNT2ZW"
)
.build();

giftCardsApi.unlinkCustomerFromGiftCardAsync(giftCardId, body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Retrieve Gift Card

Retrieves a gift card using the gift card ID.

CompletableFuture<RetrieveGiftCardResponse> retrieveGiftCardAsync(
    final String id)

Parameters

Parameter	Type	Tags	Description
id	String	Template, Required	The ID of the gift card to retrieve.

Response Type

RetrieveGiftCardResponse

Example Usage

String id = "id0";

giftCardsApi.retrieveGiftCardAsync(id).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});