# 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".

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.

### 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

Where can gift recipients redeem their eGift?

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

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

Do GiftPay eGifts expire?

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

eGift Cards in the US

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

Can GiftPay eGift Cards be combined by recipients?

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

How does a gift recipient redeem their eGift?

Helping Your Gift Recipients use their eGift Cards

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

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

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

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

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

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

Can I transfer funds between programs?

How do I cancel or delete an invoice?

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

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

What are GiftPay programs used for?

How can I request a statement of account?

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?

Account and Adding Funds

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?

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?

Viewing and Managing Past Deliveries

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

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

Is it possible to customise the branding of my eGifts?

How can I send eGift Cards to other countries?

How soon can I start sending eGifts?

Custom branding image and file specifications

How can I get a preview of my custom branding?

Getting Started with GiftPay

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

How secure is GiftPay?

Which countries can I send gift cards to?

What terms and conditions apply to each gift card?

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

Do you sell plastic gift cards?

About GiftPay

Best practices to keep your GiftPay account secure

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

Can I add another user to my account?

Does GiftPay support Single Sign On (SSO)?

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

Managing Users & Security

What ordering and delivery methods does GiftPay offer?

How are eGifts delivered?

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

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

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

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

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

API Integration Guide

Share

Share

API Integration Guide

Share

Share