# Getting started

The GiftPay API allows your system to generate eGift Cards in real time.


:::info
The API is suited to generating and sending gift cards on demand and in real-time, typically in response to user-initiated events. If you require a significant quantity of gift cards to be generated in one large batch all at once, our Bulk URLs product may be more appropriate to your needs; please discuss this with your GiftPay account manager if you are unsure.

:::

This guide gives you a general overview of the process and includes tips, best practices, and troubleshooting advice. This guide below should be read in conjunction with the [API Documentation](https://express.giftpay.com/ProgramAPIDocumentation.aspx).


:::tip
To access the full **API Documentation,** your account first needs to be provisioned for API use. Once provisioned, you can access the documentation at <https://express.giftpay.com/ProgramAPIDocumentation.aspx> (requires sign in).

:::

# Choosing the Get or Send API methods

The GiftPay API offers two alternate methods for generating or sending eGifts:

### Get method

If you use the Get method, the API response will include the gift card URL for you to store in your database and distribute to the gift recipient as required, for example in an email, or via an app.

This allows you to control the delivery format and other aspects such as method and timing. For example you can send the gift card from your own email address and design the gift card email to match your branding and design. Or you could link to a customer’s gift card(s) from within your web site or app once the customer has signed in.

When using the Get method, you will also be responsible for assisting recipients that lose access to their gift, for example if they inadvertently delete the email. For gifts generated using the Get API method, you will not be able to resend the gift using the GiftPay Express reports.

Matching gift cards between your system and the GiftPay reports (to check status or to cancel a gift) can be accomplished using either the GiftPay GiftID, or the ClientRef value your system provides with the API call.

### Send method

With this method, GiftPay sends the gift card to the recipient via the email address you supply in the API call. Emails will be sent from "\[Sender Name\] via GiftPay [noreply@giftpay.com](mailto:noreply@giftpay.com)".

Resending of gifts originally sent using the Send API method can be accomplished via the Reports section of the GiftPay Express portal.

# Development and testing

Here’s a quick overview of the process:


1. Sign up for a [sandbox account](https://sandbox.express.giftpay.com/) and verify your email address.
2. Inform your GiftPay account manager. GiftPay will then provision your sandbox account for API testing.
3. Sign in to your sandbox account to generate and obtain your sandbox API key (via **Settings** > **Manage API Settings** > **API Settings**).
4. The **API Documentation** can be accessed at <https://sandbox.express.giftpay.com/ProgramAPIDocumentation.aspx>
5. Commence development of your integration, testing your integration against the sandbox API.
6. Once your integration and testing is complete, contact your GiftPay account manager to discuss launching.

Please notify your account manager once you have created your sandbox account, as they will need to provision your sandbox account by adding an API program and test credit. You can then generate your sandbox API key via **Settings** > **Manage API Settings** when logged in to <https://sandbox.express.giftpay.com/>.

All funding within sandbox is test credit only and has no cash value. All gift cards in sandbox are test gift cards and cannot be redeemed at any actual retailers or merchants.

When testing using the sandbox, all API endpoints will begin with <https://sandbox>.

Sandbox gift cards can be branded if this is required for testing. Contact your account manager to discuss requirements.

Please note that the retailers and denominations available in sandbox are illustrative only. The retailers, denominations, terms and conditions displayed in sandbox may not match the live GiftPay product.

# Tips and best practices

### Ensure your API key remains secret

Calls to the GiftPay API must be made from your server, not from a client-side (web browser) script. This is necessary to keep your API key secret. Never share your keys in public repositories, client-side code, or with unauthorised personnel.

### Rotate API keys in accordance with your security practices

GiftPay does not enforce mandatory API key rotation. However we recommend rotating API keys regularly. At a minimum we recommend that you rotate API keys whenever a staff member with access to the keys leaves the company.

### Implement error handling & logging

Implement robust error handling, including handling for unknown errors. Log any error conditions and the associated API call details so that you can easily troubleshoot and recover.

The get or send call will be idempotent if you use the same clientref value. In other words, uniqueness is enforced on the clientref value. This allows you to safely retry an API call by using the same clientref if the original call failed with no response. If the previous call was in fact successful, the retry will not send or create a second gift card.

Design friendly and clear messaging to users who may be impacted by errors.

### Using GiftID & ClientRef

Each successful API call to send or get an eGift will also return a GiftPay GiftID, which you should record in your database. Both GiftID and ClientRef values are visible and searchable in the GiftPay reports.

Using either GiftID (GiftPay’s unique identifier) or ClientRef (your unique identifier), your team should be able to use the reports to perform reconciliations, query for particular gifts and take actions such as cancellation where required, etc.

### Request rate limits

GiftPay currently does not impose any rate limits on the Get or Send methods.

The API is suited to generating and sending gift cards on demand and in real-time, typically in response to user-initiated events. If you require a significant quantity of gift cards to be generated in one large batch all at once, our Bulk URLs product may be more appropriate to your needs; please discuss this with your GiftPay account manager if you are unsure.

If we detect a rate of API calls from your account that we would consider excessive, we’ll reach out to you to discuss the matter.

For the Balance and All Cards method, a rate limit of 1 call per day per program applies.

For the Status method, a rate limit of 1 call per GiftID per day applies. However we would encourage you to consider a rate no higher than once per week per GiftID. It’s also important to permanently stop querying the status of a gift once the status changes to “3 Used/Expired” or “-1 Cancelled”. Once a gift has either of these statuses, future status changes are not possible.

### **Monitoring available balance**

To ensure the highest performance and reliability of your integration, we strongly recommend a "Try and Fail" approach for managing gift card orders rather than a "Check then Try" workflow. Instead of checking the available balance before each order, simply proceed with the Send/Get gift card order and handle any errors such as “Insufficient balance”.

#### **Why "Try and Fail" is more efficient**

* **Reduced latency:** Checking the balance before every order doubles the number of API calls required to fulfill a single request. By attempting the order immediately, you reduce network overhead and provide a faster experience for your end users.
* **Eliminates race conditions:** In high-volume environments, a balance check may return "Success" only for the balance to be depleted by a parallel process a millisecond later. The order endpoint is the final source of truth; if funds are insufficient, it will return an insufficient balance error immediately.
* **Rate limit compliance:** Our Balance method is subject to rate limits. Frequent, redundant calls to check balance can trigger these limits, whereas the Order methods (Get/Send) are not rate-limited.

#### **Recommended best practices**


1. **Maintain a local balance:** Record your starting balance in your own database. For every successful gift card order, subtract the value from your local record to maintain a real-time "estimated" balance.
2. **Daily synchronization:** Call the Balance method once per day to reconcile your local record with the actual GiftPay program balance. This accounts for any top-ups or adjustments made during the previous 24 hours.
3. **Handle the error gracefully:** Ensure your code is configured to catch an error code for “Program gift credit exhausted”. When this error is caught, trigger an internal high-priority alert to your finance team or administrator.
4. **Redundancy:** Use this "Try and Fail" logic in conjunction with the **Low Balance Notifications** configured in your GiftPay Express dashboard to ensure you have multiple layers of protection against service interruptions.

### Setup a low balance notification

We strongly recommend that you set up a **Low Balance Notification** via the API Settings page, which requires setting a low balance threshold and adding email addresses to be notified.

You should add more than one recipient to the low balance notification, to avoid the situation where a low-balance condition is accidentally overlooked, or where a single email recipient is absent from work.

Set your low-balance threshold to give you and your finance team plenty of advance notice for when a top-up payment is required. For example, if you require 2 weeks to request an invoice and process a top-up payment to GiftPay, set your low-balance threshold at a minimum of four times your estimate weekly volume to allow for an additional buffer.

An alternative to this is to use the balance API call to regularly check the API program balance, and then implement logic or notifications in your own system to prompt your team to make a new top-up payment.

Best practice would be to implement both, to avoid a single point of failure for low balance conditions.

# Troubleshooting and common errors

### HTTP Error Code 405

The API requires an HTTP GET request, but you’re sending an HTTP POST request. Ensure your system is setup to send an HTTP GET call (not to be confused with the GiftPay Get method).

### API Status Code -1 Authorisation failed

If you get an API response status code of -1, check:


1. Are you using your sandbox key with the sandbox API? If you’re moving into production, ensure you are using your production key AND that you are using the production API URL.
2. Do you have IP whitelisting enabled? If so, check the IP address of your server or test machine and ensure it is whitelisted. Whitelisting can be enabled or disabled and IPs whitelisted via the API settings page in the GiftPay Express portal (Settings > Manage API Settings > select relevant API program > API Settings).

### API Status Code -9 Invalid parameter

If you get an API response status code of -9, check:


1. Are all required parameters included in your API call?
2. If an email address includes a + symbol, this symbol will need to be URL-encoded to %2B.

# Launching to production

Please contact your GiftPay account manager to notify of your intention to go live at least 3 business days before your launch date, ideally even earlier. Your account manager will take you through the final requirements necessary to go live with your GiftPay API integration. This will typically involve the following steps:


 1. If you do not already have one, [sign up for a live/production account](https://express.giftpay.com/?blk=true) and verify your email address.
 2. Notify your account manager once this is done, and they will setup an API program for you in your production GiftPay account.
 3. If you require custom branding and/or custom retailer selections for your gift cards, these will be setup on your API program by your account manager.
 4. You can then generate your production API key via **Settings** > **API Settings** when logged in to express.giftpay.com.
 5. You will need to make a payment and/or allocate funds to your API program.
 6. Setup a **Low Balance Notification** via the API Settings page, and add more than one email recipient. Set your low-balance threshold to give you and your finance team plenty of advance notice for when a top-up payment is required.
 7. We strongly recommend enabling **IP Address Whitelisting** and adding the IP addresses of your production server or servers. Any API calls using your API key from an IP that is not whitelisted will fail.
 8. Confirm with us before you go live so that we can be on hand to assist with troubleshooting, if required.
 9. **Reconfirm that your production environment is using the production API endpoint and key, and not the sandbox API endpoint and key.**
10. By prior arrangement with your GiftPay account manager, you can conduct a test in the live environment, and as long as you don’t activate and use the gift card produced, GiftPay can cancel and refund this test gift card.

# Getting help

If you need further help or encounter any errors during the integration process, please [contact us](https://express.giftpay.com/contactus.aspx).

API Integration Guide

How to create personalised gift card messages

How to add and edit programs

Step by Step Guides

Do GiftPay eGifts expire?

Can I buy single brand eGift Cards such as Amazon or Best Buy?

Where can gift recipients redeem their eGift?

If my eGift recipient chooses a charity donation eGift Card, how much does the charity receive?

What is the minimum and maximum value gift I can send?

eGift Cards in the US

How does a gift recipient redeem their eGift?

Can GiftPay eGift Cards be combined by recipients?

What do my gift recipients need in order to be able to redeem a GiftPay eGift Card?

A gift recipient needs a password to open their eGift, where do they get the password from?

Helping Your Gift Recipients use their eGift Cards

How do I request an invoice?

Can I pay via international bank transfer or with an international credit card?

I have just made a payment to GiftPay. When will the funds be available in my GiftPay account?

I've paid in funds to GiftPay but the balance in my account is still zero, where did the money go?

How do I cancel or delete an invoice?

What payment terms do you offer? Can I send gifts now and pay later?

If I deposit funds to GiftPay and then later change my mind, can I get a refund?

How do I use the bonus credit balance in my account?

Do the funds I have paid into my GiftPay account ever expire?

What are GiftPay programs used for?

How do I allocate funds from Unallocated Balance to a program?

Can I transfer funds between programs?

How do I avoid the need to allocate or transfer funds between programs?

How can I change my billing details such as company name and address?

How can I deposit or add funds to my GiftPay account?

How can I request a statement of account?

Account and Adding Funds

What can I do if a recipient claims they never received their eGift?

What happens if I deliver the eGift to the wrong email address?

What does it mean if an eGift has a status of "Used/Expired"?

A gift card email has bounced. What can I do?

Can I cancel an eGift after it has been sent?

What does a gift status of "Valid (Clicked)" mean?

What does a gift status of "Valid (Used)" mean?

Viewing and Managing Past Deliveries

Custom branding image and file specifications

How can I get a preview of my custom branding?

How can I send eGift Cards to other countries?

Can I claim back a gift card that is unused or expired?

How soon can I start sending eGifts?

Is it possible to customise the branding of my eGifts?

How is GiftPay better than other gift card and gift code suppliers?

Getting Started with GiftPay

How much does it cost to apply for a business account?

If the service is free, how does GiftPay make a profit?

Do you sell plastic gift cards?

Which countries can I send gift cards to?

How secure is GiftPay?

What terms and conditions apply to each gift card?

About GiftPay

Can I add another user to my account?

Does GiftPay support Single Sign On (SSO)?

How do I remove a user or team member from my GiftPay account?

Best practices to keep your GiftPay account secure

How can I add two-factor authentication (2FA) on my account?

Managing Users & Security

How are eGifts delivered?

Is there a way to use GiftPay without divulging the email addresses of my gift recipients?

Can I deliver eGifts of different value or with different messages within the same delivery batch?

What ordering and delivery methods does GiftPay offer?

Do you offer discounts for higher volumes?

Can I send eGifts to a mobile via SMS/text?

How do I schedule gifts to be delivered in the future?

How do I send a large batch of eGifts all at once?

Sending a large batch of eGifts with the same value and message

Sending a large batch of eGifts with custom values and messages

Can I send the gift cards to one email address and then forward them to my recipients?

Buying and Sending eGift Cards

Guide

GiftPay

API Integration Guide

Share

Share

API Integration Guide

Share

Share