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.

:::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 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 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.