# Welcome New to developing with Toggle? Jump in here. Welcome to our developer and integrations portal for Toggle, our powerful gift and ecommerce platform designed for hospitality. We've built this knowledgebase to help you integrate and extend Toggle using our APIs. # Getting started With our GraphQL API Toggle features a GraphQL API. This opens up many possibilities for developers to extend and integrate with us. {% hint style="success" %} Our GraphQL Endpoint is: {% endhint %} ### New to GraphQL? The GraphQL data query language is: * **A specification**. The spec determines the validity of the schema on the API server. The schema determines the validity of client calls. * **Strongly typed.** The schema defines an API’s type system and all object relationships. * **Introspective.** A client can query the schema for details about the schema. * **Hierarchical.** The shape of a GraphQL call mirrors the shape of the JSON data it returns. Nested fields let you query for and receive only the data you specify in a single round trip. * **An application layer.** GraphQL is not a storage model or a database query language. The graph refers to graph structures defined in the schema, where nodes define objects and edges define relationships between objects. The API traverses and returns application data based on the schema definitions, independent of how the data is stored. For more information about GraphQL, refer to the [documentation provided](https://graphql.org/learn/) on the official GraphQL website. ### Can I use GraphQL with in my current technology stack? GraphQL is widely supported, and there are several [server libraries available](https://graphql.org/code/) to help you get started. # Exploring our API We have an API explorer and playground. ### API Explorer Using Postmans GraphQL request, you will be able to add the Toggle URL and it will return a list of all available Queries and Mutations. {% hint style="success" %} Our Postman collection can be downloaded [here](https://api.postman.com/collections/16540815-8be4f13b-bb40-4608-88f9-6b8942da3bf5?access_key=PMAT-01JYP52YNSRAKM2JAZB56ADA26) {% endhint %}
You can build up your own queries, and responses using the GraphQL framework. The explorer is useful while you are discovering our public queries without any authentication. {% hint style="info" %} Note that the introspection query is the **only GET request** you’ll run in GraphQL. If you’re passing a body, the GraphQL request method is POST, whether it’s a query or a mutation. {% endhint %} # Authentication How to retrieve and use a bearer token. ### API Username/Password To connect to GraphQL, you will need an API username and password. You can connect existing integrations or generate new API user credentials under **Settings** > [Integrations](https://dashboard.mytoggle.io/settings/integrations). Choose the "Other" category for custom applications. ### Tokens GraphQL uses JWT tokens to authenticate API requests. So before making any request to a protected resource, you'll need to make sure you have generated a valid token, as you'll need to include this in your authorization header on each request. ### Generating a token To generate your token, use your API username/password to make a request to the `loginUser` query, which will return an Authorization header containing your token: ```graphql query LoginUser { LoginUser(username: "abcDEFghi001",password: "Password123!") { id } } ``` Note that you can login with either an **email** or a **username** via `loginUser`. Your `X-Authorization` token is returned on the `loginUser` response. Note - there is currently `Authorization` and `X-Authorization` tokens returned (they are the same). We are depreciating the `Authorization` header, so use the `X-Authorization` header to futureproof the integration. ![Token](/files/BQgxWkybnr7aUY9wmAgR) ### Using tokens in requests Whenever the user wants to access a protected route or resource, the user agent should send their token in the Authorization header using the Bearer schema. The content of the header should look like the following: ``` Authorization: Bearer ``` ### Refreshing tokens As a token is time limited, it will require a refresh after 60 minutes. When you make a new request and the Authorization header is returned, you should start using the new token for the next request. You will need to programmatically update your token and store it securely in your system each time you retrieve a new token, using it until such time that it is refreshed. ### Authentication failure If you are not authorised and you attempt to make a request to a protected query or mutation, the API will return JSON with errors. ```javascript { "errors": [ { "message": "Unauthorized", "locations": [ { "line": 2, "column": 3 } ], "customer_facing": false } ] } ``` ### Further reading It is worthwhile reading the [introduction from JWT](https://jwt.io/introduction/) which summarises how JSON Web Tokens work for more information. # Pagination / Throttling ### Pagination There are variables for limit and page available on some Queries. This is because, in theory, this query could return multiple results. You would use these variables to loop through the pages of returned results. ```graphql { Orders( page: 1 limit: 10 created_at: "2025-02-03 00:00:00" ) { data { LineItems { id created_at Transaction { merchant_transaction_reference } Card { card_reference balance expiry_time } } } } } ``` ### Throttling In order to protect our infrastructure, we throttle incoming API requests to prevent overloading. Every request made by your API user has a 'cost' which replenishes, and this threshold should be fairly high and is rarely hit for most use cases, although if you were looking to generate 10,000 cards via the API in bulk - you might hit the limit and it would be best to engage with our technical team. These limits can be configured on Toggles side, and can be increased or decreased. However, at the time of writing; * 8000 maximum threshold * 5000 replenish rate every 10mins With the response on every request, you will get an updated amount of credits returned. If you notice that you are approaching 0 (`currentlyAvailable`) then we would suggest you back off for a short period - otherwise all requests will get rejected until more credits become available. ```json "extensions": { "cost": { "actualQueryCost": 16, "throttleStatus": { "maximumAvailable": 8000, "currentlyAvailable": 7986 } } } ``` # Error handling How Toggle returns error responses Toggle returns descriptive messages for any returned errors (as opposed to error codes or numbers). For this reason, we recommend that you shouldn't try to re-interpret error strings to your own UI, and instead use them verbatim. Here's an example error response: ```javascript { "errors": [ { "message": "validation", "locations": [ { "line": 2, "column": 29 } ], "validation": { "currency": [ "This field is required" ] }, "customer_facing": false } ], "data": { "createBalanceAdjustment": null } } ``` # Overview Orders, Transactions, Line Items and more # Orders, Transactions & Line Items Some useful key structures and terms #### Orders Whether a customer purchases something through your web shop or through your EPOS, it starts life as an **Order**. An order can contain multiple items, be they gift cards or retail items or any mix of each. This is pretty typical for any ecommerce platform, as you might expect. **Transactions** Transactions represent an exchange of value between a Toggle account and an end-consumer or third party. A typical example of such an exchange would be for a new Order, whereby the transaction represents the payment taken from the consumer. However, a transaction could also relate to other monetary exchanges, such as a refund to a customer, for example. #### Line items A **Line Item** can represent an individual Sale, Redemption, Breakage (expiry), Reversal or gift card Balance Transfer (inbound or outbound). Line Items can relate to both orders and transactions. Indeed, we consider Line Items the "glue" that ultimately links everything together in our data structure. #### Cards If a new order contains a gift or other pre-paid voucher, we'll create a **Card**. A card is like a mini bank account, with a full credit/debit history associated with it. The changes of balance within an individual card we call **Balance Adjustments**. In turn, these balance changes always relate back to the **Line Item** that explains why and who made that adjustment. ### Further reading If you want to delve further into how we organise our data, our primer for FDs / CFOs might be useful further reading: [Introduction to financial reporting in Toggle >](http://academy.usetoggle.com/en/articles/4745185-introduction-to-reporting-and-exports-in-toggle) # Card number formats ### Issuer Identification Number (IIN) Toggle card unique codes are all 19 digits long. This includes an 8 digit IIN prefix of `63011900`. This is a unique, globally recognised identifier of Toggle cards. You'll see us refer to the full card unique code as a `card_reference`. {% hint style="info" %} **Card number example** `6301190060337576946` {% endhint %} ### Card aliases Toggle can also ingest cards from other providers. In such cases, the ingested cards will have both a Toggle `card_reference` but also a `card_alias.` If you are handling cards with both a `card_reference` and a `card_alias`, it is good practice to use the **alias** in all communication with the card holder, as the card holder will likely only have a copy of the card\_alias, whereas the Toggle `card_reference` is essentially masked from public view. # Tender vs Discount **What is Tender vs Discount?** Within Toggle we have the ability to store the gift card value as; * Discount (i.e. The client runs a promo giving everyone £5 voucher to come in and spend) * Tender (i.e. The guest purchases a gift card) * A mixture of both (i.e. Black Friday offer, buy £10 and get £5 topped up - would give you a £15 gift card loaded with £10 tender, and £5 discount) Because VAT is payable on redemption, and not sale (as we don't know what the gift card will be used on at point of gift card purchase) - we expose this to the platform making the purchase so they can decide how to Within a Query, can you add the `ValueSplit` field, and this will return the Tender and Discount value associated to the card. In most cases, this will show all the value in 1 of these - but there are some scenarios where the value of the card is split across both. ```graphql mutation CreateBalanceAdjustment { createBalanceAdjustment( currency: "GBP" value: -1000 merchant_id: 26 card_reference: "6301190019990640662" merchant_transaction_reference: "ABC-DEF-001" ) { value ValueSplit { tender discount } } } ``` So the response to the above would return the below; ```graphql "data": { "createBalanceAdjustment": { "value": -1000, "ValueSplit": { "tender": -750, "discount": -250 } } } ``` Which tells me that the card has been adjusted by 1000 (£10) balance, of which is split 750 tender and 250 discount. When applying the balance adjustment to the check, we'd ask that you apply the `ValueSplit.discount` as Discount (which is not VAT payable) and the `ValueSplit.tender` Tender as a tender payment (VAT payable). This ultimately helps our mutual clients accurately report on how much VAT is payable. If only a proportion of the gift card is redeemed, and it has a split value - Toggle will always take discount off a gift card before Tender. You can [read more about VAT and gift cards on our guide here >](http://academy.usetoggle.com/en/articles/2877920-vat-on-gift-cards) # Create a card Simple card creation ### Configuration | Variable | Description | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | This represents the Toggle account that you are connecting to. You can get a list of accounts linked with your API user [using an Accounts query](https://d.pr/3CAtH8). | | `sales_channel_id` |

Sales channels allow reporting by the source of an order. Commonly used are:

3 - In store

5 - B2B

7 - Guest Gratuity

| | `product_id` | All cards created need to be associated back to a product. Products can be created in the Toggle dashboard. You can retrieve a list of products for an account by using the Get Products query, or from within the Toggle interface | | `merchant_id` | Orders can be linked back to specific merchants. You can use `26` as a catch-all "third party" merchant. But if you are an official Toggle partner, you'll have been issued your own `merchant_id`. | | `order_items.fulfilment_method_id` |

The fulfilment method determines how the gift card will be delivered to the guest. Some of the methods have additional validation against them, i.e. if you want Toggle to send an email - we require the fulfilment\_email to be provided.

1 = Toggle sends an email

2 = Postal

3 = In venue (physical)

7 = Printed on Receipt
8 = Third party (i.e. you want to generate a gift card, but issue it yourself)

| | `receipt_contact` | The receipt contact details can be provided if you want to provide details against the order. If the account is configured to `Send receipt email` - then this contact will receive a receipt (not the gift card, just confirmation of order) for any order put against them. | There are several variations of this request, based on what and how you want to issue the gift card. The below example shows; * A £50 gift card * With £25 Tender (cash payment) * With £25 Discount ('free' value added) * Purchased by `Toggler.Smith+purchaser@usetoggle.co.uk` * Gift card delivered by Email to `Toggler.Brown+receipient@usetoggle.co.uk` * Sold `in-Store` {% tabs %} {% tab title="API call" %} ```graphql mutation CreateOrder { createOrder( account_id: 1 currency: "GBP" merchant_id: 24 group_fulfilment: false auto_fulfil_group_fulfilment: true merchant_transaction_reference: "912321-2139433213-12323421_26062021" total: 2500 sales_channel_id: 3 order_items: [ { product_id: 3532 custom_price_modifier_value: 5000 fulfilment_method_id: 1 generate_card_reference: true fulfilment_email: "Toggler.Brown+receipient@usetoggle.co.uk" discounts: [{ discount_type_id: 1 value: 2500 }] } ] receipt_contact: { email: "Toggler.Smith+purchaser@usetoggle.co.uk" first_name: "Toggler" last_name: "Smith" } ) { id, LineItems{ id Card{ id card_reference pin balance expiry_time card_alias_card_reference product_name } } } } ``` {% endtab %} {% endtabs %} # Custom validity rules When creating an order, validity and expiry rules that are associated with the product being purchased will be inherited by the cards created as part of that order. However, if you want to override these validity or expiry rules, you can pass in `validity_rules` and `expiry_config` variables as part of the OrderItemInput object. | Validity Rule Type | ID | Format | Description | | ---------------------------- | -- | -------------------------------- | ---------------------------------------------------------------------------- | | Valid From | 1 | UTC date in `Y-m-d H:i:s` format | The date the purchase is valid from | | Valid Until | 2 | UTC date in `Y-m-d H:i:s` format | The date the purchase is valid until | | Valid Seconds After Purchase | 3 | Integer | The number of seconds after the purchase has been made that it is valid from | To use the `validity_rules` follow the example below: ``` "validity_rules": [ { "validity_rule_type_id": 1, "rule": "2021-08-14 00:08:00" } ] ``` | Field | Format | Description | | ------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------- | | `seconds_valid_for` | Integer / NULL | The number of seconds after purchase that it will expire. NULL sets to never. | | `send_expiry_alert_days_before` | UTC date in `Y-m-d H:i:s` format / NULL | The number of days before expiry a notification will be sent to the owner. NULL sets to never. | | `hard_expire_at` | UTC date in `Y-m-d H:i:s` format / NULL | The specific time the purchase should expire. NULL sets to never. | To use the `expiry_config` follow the example below: ``` "expiry_config": { "hard_expire_at": "2021-08-14 22:59:59" } ``` ### Update a card If you want to update a card with a new validity ruleset or a new expiry config you can use the `updateCard` mutation. # Balance Check To check a card balance, pass in the `card_reference` to the `Cards` query. You can add / remove fields available via our Schema if you want to streamline / see more detail on the card from the request. {% tabs %} {% tab title="API call" %} ```graphql query Cards { Cards(card_reference: "6301190004871637839") { data { card_reference balance pin card_alias_card_reference initial_balance product_name first_top_up_value created_at used expiry_time validity_start_time ValueSplit { tender discount } } } } ``` {% endtab %} {% endtabs %} ### If no cards are found If no cards are found for your query, the API will respond with blank JSON for “Data”: ```javascript { "data": { "Cards": { "data": [] } }, "extensions": { "cost": { "actualQueryCost": 16, "throttleStatus": { "maximumAvailable": 8000, "currentlyAvailable": 7986 } } } } ``` # Redeem / Top up a card We call the change in balance of a card a "balance adjustment. So to create a redemption, make a mutation request to `createBalanceAdjustment` with a negative value, or pass in a positive value if you want to top up a cards value. {% tabs %} {% tab title="API call" %} ```graphql mutation CreateBalanceAdjustment { createBalanceAdjustment( currency: "GBP" value: -1000 merchant_id: 26 unit_epos_reference: "2251799825000010" card_reference: "6301190088474564102" merchant_transaction_reference: "ABC-DEF-GHI-1234123-123-0033" ) { id value LineItem { id Card { card_reference card_alias_card_reference balance expiry_time product_name } } ValueSplit { tender discount } } } ``` {% endtab %} {% endtabs %} # Reversals When either creating an order or redeeming a card, you may also need to support the functionality to reverse that action. For example, if a staff member selling or redeeming the card on-site needs to undo what they did - which could be a gift card sale or a balnace adjustment. To reverse a transaction, make a mutation request to `createReversal`. You will need to pass in the Toggle line\_item\_id of the transaction you want to reverse. ```graphql mutation CreateReversal { createReversal( merchant_transaction_reference: "abc-def-ghi-123" merchant_id: 24 unit_epos_reference: "Epos01" ReversalItems: { line_item_id: 11001614 shipping_refund: false } ) { id value LineItems { value Card { card_reference balance } } } } ``` ### What line item ID should I use? There are 2 ways you can get the line\_item\_id. 1. You can do a `get line_item_id` call To find this, you'll first need to make another query to fetch this for the transaction that you are trying to reverse, using the `merchant_transaction_reference` you passed in the original call. {% tabs %} {% tab title="API query" %} ```graphql query LineItems { LineItems(merchant_transaction_reference: "abc-def-123-123-423-aaasde4") { data { id } } } ``` {% endtab %} {% endtabs %} This will give you the line item ID for the transaction you are trying to reverse. 2. Whenever you create or balance adjust a card, you can add the ID to the query and have it returned in the response This will require you to store that ID against the transaction, then later surface it to us for the reversal. ### What merchant transaction reference should I use? The `merchant_transaction_reference` you pass in for the reversal is expected to be a uniquely generated reference (e.g. an identifier of the reversal transaction on the till). If your system doesn't create transaction references for reversals, then you could potentially just append "-REVERSAL" on the end of the original reference. e.g. "test-123-123-123-REVERSAL" This use-case is aimed at book-keepers and for troubleshooting, whereby if someone downloaded, say, a CSV list of till transactions (e.g. card sales, redemptions, reversals etc.) and each has a unique till transaction identifier, then if someone pulled down an equivalent CSV list of balance adjustments on the Toggle side, someone could - if needs be - match them up with your unique identifier for each one. ### What epos\_reference should I use? If this is reversed at a specific location, the location that is performing the reversal should be provided. This field is optional though, as some reversals are done centrally rather than at site. ### What about partial refunds? With the `CreateReversal` mutation you can only refund the full value of the `LineItem` you are wanting to refund. In order to do partial refunds you would need to refund the whole line item and then subsequently create a new balance adjustment with the corrected value. # Overview Toggle webhooks provides third-party applications with real-time information, meaning you get data immediately as an event happens on Toggle. Details of event payloads are provided in this guide. # Getting started To get started using Toggle webhooks... 1. Set up a public web server with a valid SSL certificate that accepts POST requests. 2. Take a note of your domain and end-point and ask the Toggle support team to start sending webhooks to this URL. 3. The support team will supply with you with a webhook secret and let you know when you can start expecting to receive payloads. # Authentication & responses ### Webhooks secret A webhook secret is a key used to calculate the `HTTP_TOGGLE_SIGNATURE` and is passed in the header of every request. This adds a security layer between the two apps (Toggle and your App) to make sure the payload that you receive has not been tampered with. The signature is a hash of the entire payload, signed using the signing secret that we have supplied to you. Every request received by your application should compare this signature to your own, in order to ensure that it is not fraudulent. The secret will be provided by the Toggle support team when you first set up a web hook with us. ### Handling requests Before accepting any webhook sent to you, you should verify it by checking the hashed contents. The following example (in PHP) is how you could calculate the secret and check the payload. ```php function verifySignature($signingSecret, $payload) { $sig_header = $_SERVER['HTTP_TOGGLE_SIGNATURE']; $computedSignature = hash_hmac('sha256', $payload, $signingSecret); return hash_equals($sig_header, $computedSignature); } ``` ### Response and attempts We will expect a 200 response from your server. In case of failure we will attempt to dispatch the web hook **another 3 times** before giving up. In order to prevent timeouts, we recommend that your server responds to webhook events prior to any logic being executed. We will disable your endpoint if we receive invalid responses from your server over consecutive days. # Events # Card.balance\_adjusted This event is dispatched when a [card balance changes](http://academy.usetoggle.com/en/articles/3578378-orders-cards-and-balance-adjustments), for example during initial top-up/creation, redemption or reversal. We include the latest balance adjustment change in this payload. ### Example payload ```javascript { "id": 567, "object": "event", "api_version": "3.2", "webhook_version": "1.0", "created_at": "2021-04-11T16:01:22.000000Z", "type": "card.balance_adjusted", "data": { "object": { "object": "card", "id": 355, "balance": 1000, "card_reference": "6301190045888067809", "pin": 134702, "expiry_time": "2021-03-27T23:59:59.000000Z", "validity_start_time": "2021-03-12T00:00:00.000000Z", "personal_message": null, "qr_code_url": "https://apimytoggleio-dev.airship.co.uk/qrcodegenerator/6301190045888067809", "account_id": 1, "purchaser_contact": { "object": "contact", "id": 703, "email": "john@example.co.uk", "first_name": "John", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": null }, "product": { "object": "product", "id": 4, "name": "Gift Card", "short_description": "Gift Card", "long_description": "Gift Card", "image": { "object": "image", "id": 13, "url": "https://apimytoggleio-dev.airship.co.uk//storage/images/1_1616686008.png" }, "product_type": { "object": "product_type", "id": 1, "name": "Gift Card" } }, "contact": null, "currency": { "object": "currency", "id": 1, "name": "Sterling", "denomination": 100, "iso_currency_code": "GBP" }, "latest_balance_adjustment": { "object": "balance_adjustment", "id": 623, "created_at": "2021-04-11T16:01:22.000000Z", "value": 1000, "line_item": { "object": "line_item", "id": 623, "personalised_message": null, "value": 1000, "line_item_type": { "object": "line_item_type", "id": 1, "name": "Sale" }, "transaction": { "object": "transaction", "id": 617, "value": 0, "transaction_discount_value": 0, "account_id": 1, "currency": { "object": "currency", "id": 1, "name": "Sterling", "denomination": 100, "iso_currency_code": "GBP" }, "unit": null } } }, "card_alias": { "object": "card_alias", "card_alias": "18347923487", "card_alias_pin": "1234", } } } } ``` # Card.card\_reference\_updated This event is dispatched when a `card_reference` is updated ### Example payload ```javascript { "id": 576, "object": "event", "api_version": "3.2", "webhook_version": "1.0", "created_at": "2021-04-11T16:06:54.000000Z", "type": "card.card_reference_updated", "data": { "object": { "object": "card", "id": 356, "balance": 1000, "card_reference": "12345", "pin": "1234", "expiry_time": "2021-03-27T23:59:59.000000Z", "validity_start_time": "2021-03-12T00:00:00.000000Z", "personal_message": null, "qr_code_url": "https://apimytoggleio-dev.airship.co.uk/qrcodegenerator/12345", "account_id": 1 } } } ``` On This Page[Example payload](https://developers.usetoggle.com/docs/web-hooks/docs/Events/1.1-Card.card_reference_updated.md#example-payload) # Card.expiry\_reminder This event dispatched when an [expiring balance reminder](http://academy.usetoggle.com/en/articles/2835135-setting-and-managing-gift-validity-in-toggle) occurs. ### Example payload ```javascript { "id": 590, "object": "event", "api_version": "3.2", "webhook_version": "1.0", "created_at": "2021-04-11T16:51:03.000000Z", "type": "card.expiry_reminder", "data": { "object": { "object": "card", "id": 331, "balance": 1000, "card_reference": "6301190045418594090", "pin": "198303", "expiry_time": "2021-03-27T23:59:59.000000Z", "validity_start_time": "2021-03-12T00:00:00.000000Z", "personal_message": null, "qr_code_url": "https://apimytoggleio-dev.airship.co.uk/qrcodegenerator/6301190045418594090", "account_id": 1, "purchaser_contact": { "object": "contact", "id": 655, "email": "john@example.co.uk", "first_name": "John", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": null }, "product": { "object": "product", "id": 4, "name": "Gift Card", "short_description": "Gift Card", "long_description": "Gift Card", "image": { "object": "image", "id": 13, "url": "https://apimytoggleio-dev.airship.co.uk//storage/images/1_1616686008.png" }, "product_type": { "object": "product_type", "id": 1, "name": "Gift Card" } }, "contact": { // N.B. Could also be null if card not registered to anyone "object": "contact", "id": 704, "email": "john@example.co.uk", "first_name": null, "last_name": null, "phone_number": null, "marketing_opt_in_at": null }, "currency": { "object": "currency", "id": 1, "name": "Sterling", "denomination": 100, "iso_currency_code": "GBP" }, "card_alias": { "object": "card_alias", "card_alias": "18347923487", "card_alias_pin": "1234", } } } } ``` On This Page[Example payload](https://developers.usetoggle.com/docs/web-hooks/docs/Events/2.-Card.expiry_reminder.md#example-payload) # Card.registered This event is dispatched when a [card is registered](http://academy.usetoggle.com/en/articles/2477944-how-your-customers-can-register-a-gift-card-they-ve-received). ### Example payload ```javascript { "id": 583, "object": "event", "api_version": "3.2", "webhook_version": "1.0", "created_at": "2021-04-11T16:36:10.000000Z", "type": "card.registered", "data": { "object": { "object": "card", "id": 356, "balance": 1000, "card_reference": "12345", "pin": "1234", "expiry_time": "2021-03-27T23:59:59.000000Z", "validity_start_time": "2021-03-12T00:00:00.000000Z", "personal_message": null, "qr_code_url": "https://apimytoggleio-dev.airship.co.uk/qrcodegenerator/12345", "account_id": 1, "purchaser_contact": { "object": "contact", "id": 705, "email": "john@example.co.uk", "first_name": "Smith", "last_name": "Cole", "phone_number": null, "marketing_opt_in_at": null }, "product": { "object": "product", "id": 4, "name": "Gift Card", "short_description": "Gift Card", "long_description": "Gift Card", "image": { "object": "image", "id": 13, "url": "https://apimytoggleio-dev.airship.co.uk//storage/images/1_1616686008.png" }, "product_type": { "object": "product_type", "id": 1, "name": "Gift Card" } }, "contact": { "object": "contact", "id": 708, "email": "john@example.co.uk", "first_name": "John", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": "2021-04-11T16:36:10.000000Z" }, "currency": { "object": "currency", "id": 1, "name": "Sterling", "denomination": 100, "iso_currency_code": "GBP" }, "card_alias": null } } } ``` # Card.send\_recipient\_email This event is dispatched whenever a card recipient email is sent. ### Example payload ```javascript { "id": 568, "object": "event", "api_version": "3.2", "webhook_version": "1.0", "created_at": "2021-04-11T16:01:27.000000Z", "type": "card.send_recipient_email", "data": { "object": { "object": "card", "id": 355, "balance": 1000, "card_reference": "6301190045888067809", "pin": 134702, "expiry_time": "2021-03-27T23:59:59.000000Z", "validity_start_time": "2021-03-12T00:00:00.000000Z", "personal_message": null, "qr_code_url": "https://apimytoggleio-dev.airship.co.uk/qrcodegenerator/6301190045888067809", "account_id": 1, "purchaser_contact": { "object": "contact", "id": 703, "email": "john@example.co.uk", "first_name": "John", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": null }, "product": { "object": "product", "id": 4, "name": "Gift Card", "short_description": "Gift Card", "long_description": "Gift Card", "image": { "object": "image", "id": 13, "url": "https://apimytoggleio-dev.airship.co.uk//storage/images/1_1616686008.png" }, "product_type": { "object": "product_type", "id": 1, "name": "Gift Card" } }, "contact": null, "currency": { "object": "currency", "id": 1, "name": "Sterling", "denomination": 100, "iso_currency_code": "GBP" }, "line_item_fulfilment": { "object": "line_item_fulfilment", "id": 350, "tracking_reference": null, "postage_type": null, "address": null, "contact": { "object": "contact", "id": 704, "email": "john@example.co.uk", "first_name": null, "last_name": null, "phone_number": null, "marketing_opt_in_at": null }, "fulfilment_method": { "object": "fulfilment_method", "id": 1, "name": "Email" } }, "card_alias": { "object": "card_alias", "card_alias": "18347923487", "card_alias_pin": "1234", } } } } ``` # Card.resend\_recipient\_email This event is dispatched whenever a [card recipient email is resent](http://academy.usetoggle.com/en/articles/2336058-resending-a-gift-email-and-or-receipt-email). ### Example payload ```javascript { "id": 124600, "object": "event", "api_version": "3.10", "webhook_version": "1.0", "created_at": "2021-05-24T11:39:55.000000Z", "type": "card.resend_recipient_email", "data": { "object": { "object": "resend_recipient_email", "mail_to_address": "johnsmith@example.com", "card": { "object": "card", "id": 510212, "balance": 1500, "card_reference": "6301190045888067809", "pin": "329732", "expiry_time": null, "validity_start_time": "2021-05-24T10:24:09.000000Z", "personal_message": "", "qr_code_url": "https://api.mytoggle.io/qrcodegenerator/6301190045888067809", "account_id": 1, "purchaser_contact": { "object": "contact", "id": 434278, "email": "janesmith@example.com", "first_name": "Jane", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": null }, "product": { "object": "product", "id": 3251, "name": "Joiner's Gift Card", "short_description": "Gift the gift of bread.", "long_description": "Only available at the Joiner's Kitchen", "image": null, "product_type": { "object": "product_type", "id": 1, "name": "Gift Card" } }, "contact": { "object": "contact", "id": 434282, "email": "jimsmith@example.co.uk", "first_name": "Jim", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": null }, "currency": { "object": "currency", "id": 1, "name": "Sterling", "denomination": 100, "iso_currency_code": "GBP" }, "line_item_fulfilment": { "object": "line_item_fulfilment", "id": 494221, "tracking_reference": null, "postage_type": null, "address": null, "contact": { "object": "contact", "id": 434279, "email": "johnsmith@example.com", "first_name": null, "last_name": null, "phone_number": null, "marketing_opt_in_at": null }, "fulfilment_method": { "object": "fulfilment_method", "id": 1, "name": "Email" } }, "card_alias": { "object": "card_alias", "card_alias": "18347923487", "card_alias_pin": "1234", } } } } } ``` # Order.created This event is dispatched an order in Toggle is created. Orders are created in all instances where a card is initially created e.g. in-venue, free of charge (FOC), web shop, 3rd party etc. An order can contain [one line\_item (e.g. card) or many line\_items](http://academy.usetoggle.com/en/articles/3578378-orders-cards-and-balance-adjustments). However, an order will always only have one transaction associated with it. Typically, the transaction on an order will be the payment transaction that was used to create that order. Note that in some cases the transaction value won’t be the same as the order value, such as in discounted or FOC orders. Also note that the order value includes the postage value – in the case of postal cards. For each line\_item – as you can see in the example payload below – you can check which product and/or method of fulfilment was defined for each item in the order. ### Example payload ```javascript { "id": 570, "object": "event", "api_version": "3.2", "webhook_version": "1.0", "created_at": "2021-04-11T16:01:27.000000Z", "type": "order.created", "data": { "object": { "object": "order", "id": 350, "postage_value": 0, "value": 1000, "account_id": 1, "transaction": { "object": "transaction", "id": 617, "value": 0, "transaction_discount_value": 1000, "account_id": 1, "currency": { "object": "currency", "id": 1, "name": "Sterling", "denomination": 100, "iso_currency_code": "GBP" }, "unit": null }, "receipt_contact": { "object": "contact", "id": 703, "email": "john@example.co.uk", "first_name": "John", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": null }, "line_items": [ { "object": "line_item", "id": 623, "personalised_message": null, "value": 1000, "line_item_type": { "object": "line_item_type", "id": 1, "name": "Sale" }, "product": { "object": "product", "id": 4, "name": "Gift Card", "short_description": "Gift Card", "long_description": "Gift Card", "image": { "object": "image", "id": 13, "url": "https://apimytoggleio-dev.airship.co.uk//storage/images/1_1616686008.png" }, "product_type": { "object": "product_type", "id": 1, "name": "Gift Card" } }, "card": { "object": "card", "id": 355, "balance": 1000, "card_reference": "6301190045888067809", "pin": "134702", "expiry_time": "2021-03-27T23:59:59.000000Z", "validity_start_time": "2021-03-12T00:00:00.000000Z", "personal_message": null, "qr_code_url": "https://apimytoggleio-dev.airship.co.uk/qrcodegenerator/6301190045888067809", "account_id": 1, "purchaser_contact": { "object": "contact", "id": 703, "email": "john@example.co.uk", "first_name": "John", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": null }, "contact": null, "card_alias": { "object": "card_alias", "card_alias": "18347923487", "card_alias_pin": "1234", } }, "line_item_fulfilment": { "object": "line_item_fulfilment", "id": 350, "tracking_reference": null, "postage_type": null, "address": null, "contact": { "object": "contact", "id": 704, "email": "john@example.co.uk", "first_name": null, "last_name": null, "phone_number": null, "marketing_opt_in_at": null }, "fulfilment_method": { "object": "fulfilment_method", "id": 1, "name": "Email" } } } ] } } } ``` # Order.cancelled This event is dispatched when an [order in Toggle is cancelled](http://academy.usetoggle.com/en/articles/2514048-issuing-refunds-cancelling-online-orders). Orders are marked as cancelled when all line\_items within the order are reversed. ### Example payload ```javascript { "id": 572, "object": "event", "api_version": "3.2", "webhook_version": "1.0", "created_at": "2021-04-11T16:04:58.000000Z", "type": "order.cancelled", "data": { "object": { "object": "order", "id": 350, "postage_value": 0, "value": 1000, "account_id": 1 } } } ``` # Order.send\_receipt\_email This event is dispatched whenever an order receipt email is sent. ### Example payload ```javascript { "id": 569, "object": "event", "api_version": "3.2", "webhook_version": "1.0", "created_at": "2021-04-11T16:01:27.000000Z", "type": "order.send_receipt_email", "data": { "object": { "object": "order", "id": 350, "postage_value": 0, "value": 1000, "account_id": 1, "transaction": { "object": "transaction", "id": 617, "value": 0, "transaction_discount_value": 1000, "account_id": 1, "currency": { "object": "currency", "id": 1, "name": "Sterling", "denomination": 100, "iso_currency_code": "GBP" }, "unit": null }, "receipt_email": { "object": "contact", "id": 703, "email": "john@example.co.uk", "first_name": "John", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": null }, "line_items": [ { "object": "line_item", "id": 623, "personalised_message": null, "value": 1000, "line_item_type": { "object": "line_item_type", "id": 1, "name": "Sale" }, "product": { "object": "product", "id": 4, "name": "Gift Card", "short_description": "Gift Card", "long_description": "Gift Card", "image": { "object": "image", "id": 13, "url": "https://apimytoggleio-dev.airship.co.uk//storage/images/1_1616686008.png" }, "product_type": { "object": "product_type", "id": 1, "name": "Gift Card" } }, "card": { "object": "card", "id": 355, "balance": 1000, "card_reference": "6301190045888067809", "pin": "134702", "expiry_time": "2021-03-27T23:59:59.000000Z", "validity_start_time": "2021-03-12T00:00:00.000000Z", "personal_message": null, "qr_code_url": "https://apimytoggleio-dev.airship.co.uk/qrcodegenerator/6301190045888067809", "account_id": 1, "purchaser_contact": { "object": "contact", "id": 703, "email": "john@example.co.uk", "first_name": "John", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": null }, "contact": null, "card_alias": { "object": "card_alias", "card_alias": "18347923487", "card_alias_pin": "1234", } }, "line_item_fulfilment": { "object": "line_item_fulfilment", "id": 350, "tracking_reference": null, "postage_type": null, "address": null, "contact": { "object": "contact", "id": 704, "email": "john@example.co.uk", "first_name": null, "last_name": null, "phone_number": null, "marketing_opt_in_at": null }, "fulfilment_method": { "object": "fulfilment_method", "id": 1, "name": "Email" } } } ] } } } ``` # Order.send\_cancellation\_email This event is dispatched whenever an order cancellation email should be sent. ### Example payload ```javascript { "id": 589, "object": "event", "api_version": "3.2", "webhook_version": "1.0", "created_at": "2021-04-11T16:48:12.000000Z", "type": "order.send_cancellation_email", "data": { "object": { "object": "order", "id": 346, "postage_value": 0, "value": 1000, "account_id": 1, "transaction": { "object": "transaction", "id": 612, "value": 0, "transaction_discount_value": 1000, "account_id": 1, "currency": { "object": "currency", "id": 1, "name": "Sterling", "denomination": 100, "iso_currency_code": "GBP" }, "unit": null }, "receipt_email": { "object": "contact", "id": 695, "email": "john@example.co.uk", "first_name": "John", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": null }, "line_items": [ { "object": "line_item", "id": 618, "personalised_message": null, "value": 1000, "line_item_type": { "object": "line_item_type", "id": 1, "name": "Sale" }, "product": { "object": "product", "id": 4, "name": "Gift Card", "short_description": "Gift Card", "long_description": "Gift Card", "image": { "object": "image", "id": 13, "url": "https://apimytoggleio-dev.airship.co.uk//storage/images/1_1616686008.png" }, "product_type": { "object": "product_type", "id": 1, "name": "Gift Card" } }, "card": { "object": "card", "id": 351, "balance": 0, "card_reference": "6301190019865780288", "pin": "585052", "expiry_time": "2021-03-27T23:59:59.000000Z", "validity_start_time": "2021-03-12T00:00:00.000000Z", "personal_message": null, "qr_code_url": "https://apimytoggleio-dev.airship.co.uk/qrcodegenerator/6301190019865780288", "account_id": 1, "purchaser_contact": { "object": "contact", "id": 695, "email": "john@example.co.uk", "first_name": "John", "last_name": "Smith", "phone_number": null, "marketing_opt_in_at": null }, "contact": null }, "line_item_fulfilment": { "object": "line_item_fulfilment", "id": 346, "tracking_reference": null, "postage_type": null, "address": null, "contact": { "object": "contact", "id": 696, "email": "john@example.co.uk", "first_name": null, "last_name": null, "phone_number": null, "marketing_opt_in_at": null }, "fulfilment_method": { "object": "fulfilment_method", "id": 1, "name": "Email" } } } ] } } } ``` # Payment.failed Event dispatched when a payment in review is rejected. No order will be created after a payment has been rejected. ### Example payload ```javascript { "id":203, "object":"event", "api_version":"1.9", "webhook_version":"1.0", "created_at":"2020-02-20T14:39:38.000000Z", "type":"payment.failed", "data":{ "object":{ "object":"pending_order", "id":3, "merchant_transaction_reference":"p1_fsmbgo8267kbcdubcdas", "receipt_email":"fred@airship.co.uk", "account_id": 1, } } } ``` # Payment.review\_opened This event is dispatched when a [payment goes into review](http://academy.usetoggle.com/en/articles/2728810-reducing-chargeback-fraud-with-stripe-radar-toggle). This happens when a payment gateway (e.g. Stripe) has suspended a payment, pending review. An order will not be created until the payment has been reviewed in the payment gateway, after which the order.created event will be dispatched. ### Example payload ```javascript { "id":205, "object":"event", "api_version":"1.9", "webhook_version":"1.0", "created_at":"2020-02-20T14:40:55.000000Z", "type":"payment.review_opened", "data":{ "object":{ "object":"pending_order", "id":3, "merchant_transaction_reference":"p1_fsmbgo8267kbcdubcdas", "receipt_email":"fred@airship.co.uk", "account_id": 1 } } } ``` # Fulfilment.dispatched This event dispatched when an fulfilment is marked as dispatched. ### Example payload ```javascript { "id": 605, "object": "event", "api_version": "3.2", "webhook_version": "1.0", "created_at": "2021-04-11T17:31:56.000000Z", "type": "fulfilment.dispatched", "data": { "object": { "object": "line_item_fulfilment", "id": 354, "tracking_reference": null, "postage_type": { "object": "postage_type", "id": 1, "delivery_name": "first class", "price": 100, "tracked": false, "currency": { "object": "currency", "id": 1, "name": "Sterling", "denomination": 100, "iso_currency_code": "GBP" }, "postage_category": { "object": "postage_category", "id": 1, "name": "first class", "tracked": false } }, "address": { "object": "address", "id": 8, "name": "John Smith", "address_line_1": "123, Letsby Ave", "address_line_2": null, "town_city": "Sheffield", "postcode": "S1 1AY" }, "contact": null, "fulfilment_method": { "object": "fulfilment_method", "id": 2, "name": "Postal" }, "line_items": [ { "object": "line_item", "id": 630, "personalised_message": null, "value": 1000, "line_item_type": { "object": "line_item_type", "id": 1, "name": "Sale" }, "product": { "object": "product", "id": 4, "name": "Gift Card", "short_description": "Gift Card", "long_description": "Gift Card" }, "product_type": { "object": "product_type", "id": 1, "name": "Gift Card" }, "transaction": { "object": "transaction", "id": 624, "value": 0, "transaction_discount_value": 1100, "account_id": 1, "currency": { "object": "currency", "id": 1, "name": "Sterling", "denomination": 100, "iso_currency_code": "GBP" }, "unit": null } } ] } } } ``` # EPOS & Ordering If you're an EPOS or Ordering partner, start here. # Overview If you are an EPOS or Ordering / Pay at Table partner looking to integrate Toggle into your platform, this guide will help sign-post the things you'll likely want to support within our application. Typical usecases for EPOS integrations are; * Authentication * Balance Checks * Balance Adjustments (Redeem / Top up) * Gift card Sales (Physical / Receipt / Digital) * Reversals ### Gift card redemptions The first thing you need to accommodate is allowing guest to redeem their Toggle gift card. This could be in one of several scenarios, depending on your particular ecosystem. **For EPOS...** * A physical gift card that card that can be scanned (QR code), swiped (Mag stripe) or manually keyed in * A digital gift card that can be scanned (QR code) or manually keyed in Take a look at some of our EPOS partners' integrations for inspiration: * [Centegra >](http://academy.usetoggle.com/en/articles/5021000-connect-your-toggle-account-with-centegra) * [Access POS >](http://academy.usetoggle.com/en/articles/2757176-using-toggle-on-access-epos) * [Many more here >](http://academy.usetoggle.com/en/collections/1411886-integrations) **For Ordering / Pay at Table apps...** * A physical gift card can be scanned in using a device camera (QR code) or manually keyed in * A digital card can be manually keyed in, or scanned (from another device) or potentially (if your app allows deep linking), a call-to-action from the digital gift into your app with the gift code passed via a URL parameter. Take a look at some of our Ordering partners' integrations for inspiration: * [Orderswift >](http://academy.usetoggle.com/en/articles/5022015-redeem-toggle-gift-cards-on-orderswift) * [Vita Mojo >](http://academy.usetoggle.com/en/articles/4811675-connecting-your-toggle-vita-mojo-accounts) * [Many more here >](http://academy.usetoggle.com/en/collections/1411886-integrations) **Redemption flow** In all cases, your application should check the card has sufficient balance, allow a full or partial redemption, and apply the gift card payment to the customer's basket. If a customer payment/checkout is subsequently cancelled, you should also reverse the gift card redemption (effectively putting the balance back onto the gift card). **Tender vs Discount** The API response we send back after a redemption will tell you whether to treat it as a discount (money-off, reducing sales tax/VAT) or as tender (treat the same as cash). In some cases, a redemption could be a mixture of discount and tender. We go into this in more detail in subsequent pages in this guide. ### Gift card purchases For EPOS partners, you should also accommodate guests who wish to purchase a gift card while they are on-site. Ordering partners may also wish to consider allowing a guest to purchase a gift as part your app. **Physical cards via EPOS** The most common scenario is for a site to have a stock of unloaded physical gift cards, pre-printed and/or encoded with gift card numbers. These will have been pre-ordered with help from our Customer Success team and shipped out to sites. To sell a card, you should the POS user an option to sell a gift card, take payment as normal, and then attach a gift card number from the unsold stock (by swiping, scanning or keying in the number), before sending the order up to the Toggle API to load the desired balance onto the card. Additionally, if a customer wants to buy a gift card while they are on site, staff members should be able to sell a gift card through your POS. **Digital cards** For EPOS and Ordering apps, you could also allow the selling of a digital card. In this scenario, you would take payment from a guest as normal, then make an API request to Toggle to create and load a gift card, optionally sending a copy of the gift digitally to the guests email address. **Till receipt cards** Some partners also allow the selling / issuing of a gift on the till receipt. This is essentially the same as a digital card, though you would include a copy of the gift card number returned on a printed till receipt. ### **Reversals** In all cases, you should allow for the operator of the POS or the customer to subsequently cancel / undo the order. You should reverse the transaction via our API, effectively voiding the card balance load. # Accreditation For approved partner integrations, you will need to complete our accreditation process. ### Accreditation test cases You will be asked to complete a series of test cases to ensure all use-cases have been met. Here is a sample list of test cases: 1. To test successful API authorisation 2. To test failed API authorisation with incorrect username/password 3. To test failed API request due to invalid or expired token 4. To test a successful creation of a new physical card 5. To test a failed order creation, with an invalid merchant\_id 6. To test failed card creation due to a missing card\_reference 7. To test a failed order creation, with invalid or missing product\_id 8. To test a failed order creation, with invalid or missing currency 9. To test a failed order creation, with invalid or missing sales\_channel\_id 10. To test a successful debit transaction 11. To test a successful credit transaction 12. To test a failed balance adjustment with an incorrect merchant\_id 13. To test a failed debit due to negative balance 14. To test a failed debit with an incorrect value field format 15. To test a failed top-up with a duplicate merchant\_transaction\_reference 16. To test a top-up balance adjustment with an empty card\_reference field 17. To test a failed top up due to an incorrect unit\_epos\_reference 18. To test a failed balance adjustment, with invalid or missing currency 19. To test a failed order creation, with invalid or missing fulfilment\_method\_id 20. To test a successful reversal of a card creation 21. To test a successful reversal of debit transaction 22. To test a successful reversal of credit transaction 23. To test a failed reversal due to missing or invalid line\_item\_id 24. To test a successful query on a card. 25. To test a failed card query, with an invalid card\_reference # Configuration variables Your application will need to keep a configuration of variables to use for each distinct Toggle account (e.g. for each of our mutual shared customers/clients). These are summarised below. | Variable | Description | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sales_channel_id` | For POS integrations, use `3` as the sales\_channel\_id when creating orders – this is a permanent ID used across all accounts for in-store transactions. | | `fulfilment_method_id` |

Used when creating orders, for in-venue physical card orders, this can always be configured as 3 (In-venue)

If you issue digital cards from your application, and would like Toggle to send the guest the gift card - this would be 1 (Email)

If you issue receipt printed cards from your application, this would be 7 (Receipt)

| | `currency_id` | Default to `1` (£ sterling), but leave this as something that can be configured as well, this will ensure the integration is future-proofed to handle other currency IDs in future. | | `account_id` | `account_id` will be manually configured, and will be provided during onboarding of a new mutual customer. Email to request an `account_id`. | | `merchant_id` | This identifies you as an an approved merchant on our platform. Email to request this. | | `unit_epos_reference` | This refers to the unique location ID, passed to Toggle so it knows the location where the transaction was made. This needs to be matched with the configured EPOS references in each Toggle customer's account. See [here for more information](http://academy.usetoggle.com/en/articles/2892479-setting-up-toggle-for-multiple-sites). | | `merchant_transaction_reference` | This refers to the unique reference created by the till when the transaction is made. You will generate and pass this to our API when handling transactions. | # Create a card To create an order in Toggle, make a mutation request to `createOrder`. {% tabs %} {% tab title="Physical" %} If you want to capture Digital sales on the POS, the main differences from the basic [create a card](/basics/create-a-card) are; * `fulfilment_method_id` = 3 (in store gift sale) * `card_reference` = you need to provide the physical card number that is being sold ```graphql mutation CreateOrder { createOrder( account_id: 1 currency: "GBP" merchant_id: 24 group_fulfilment: true auto_fulfil_group_fulfilment: true merchant_transaction_reference: "abc-def-123-123-423-aaas555" unit_epos_reference: "2251799825000010" total: 5000 sales_channel_id: 3 order_items: [ { product_id: 3532 custom_price_modifier_value: 5000 fulfilment_method_id: 3 generate_card_reference: false card_reference: "6301190088474564102" } ] ) { id, LineItems{ id Card{ id card_reference pin balance expiry_time card_alias_card_reference product_name } } } } ``` {% endtab %} {% tab title="Digital" %} If you want to capture Digital sales on the POS, the main differences from the basic [create a card](/basics/create-a-card) are; * `fulfilment_method_id` = 1 (this will ensure Toggle sends an email) * `fulfilment_email` = Guests email address, required for us to email gift card ```graphql mutation CreateOrder { createOrder( account_id: 1 currency: "GBP" merchant_id: 24 group_fulfilment: false auto_fulfil_group_fulfilment: true merchant_transaction_reference: "912321-2139433213-12323421_26062021" total: 2500 sales_channel_id: 3 order_items: [ { product_id: 3532 custom_price_modifier_value: 5000 fulfilment_method_id: 1 generate_card_reference: true fulfilment_email: "guest+receipient@usetoggle.co.uk" } ] ) { id, LineItems{ id Card{ id card_reference pin balance expiry_time card_alias_card_reference product_name } } } } ``` {% endtab %} {% tab title="Receipt" %} ```graphql mutation CreateOrder { createOrder( account_id: 1 currency: "GBP" merchant_id: 24 group_fulfilment: true auto_fulfil_group_fulfilment: true merchant_transaction_reference: "abc-def-123-123-423-aaas555" unit_epos_reference: "2251799825000010" total: 5000 sales_channel_id: 3 order_items: [ { product_id: 3532 custom_price_modifier_value: 5000 fulfilment_method_id: 7 generate_card_reference: true } ] ) { id, LineItems{ id Card{ id card_reference pin balance expiry_time card_alias_card_reference product_name } } } } ``` {% endtab %} {% endtabs %} ### Where should I get the card reference when creating an order? The use-case here is that a POS operative would have a stack of unused cards (not associated with an order yet) on-site which would be keyed or swiped/scanned in as the card order is created on EPOS. So to simulate this scenario while developing, you need some 'blank' cards to create orders with. If you haven't yet been provided any, ask our support team to create some card numbers, which we will provide to you as a CSV. You can then use card numbers from the CSV during development, as if they were unsold stock on site. You will also need to switch your account to use Magnetic Stripe cards under [General Settings](https://dashboard.mytoggle.io/settings/general). ### What product ID should you use? All orders in Toggle are linked to a product. This would enable you to create a menu of product options to choose from when selling a gift card or experience. There is an example query of how to retrieve a list of products from the API. Alternatively, we do have a default product on every account which you can use if you wish to simply sell a single gift card product type and avoid the extra overhead of creating a menu of product options to choose from. To retrieve the default product ID, use the same query as above and find a product called "**In-store Gift**". This Product ID will be unique per customer/client account, but you only need to retrieve and configure this id a single time as it will not change for an account once that account exists. ### What value should I use for "total"? This should equal the total of the cards being created. e.g. if a customer is buying 1x card for £20, the total would be 2000. If they are buying 2x £20 cards, and it’s being done as a single order, the total would be passed as 4000. ### Common troubleshooting tips #### Unit EPOS Reference errors If you receive this validation response: ``` "unit_epos_reference" : [ "This field is not of an expected value" ] ``` This is because the unit\_epos\_reference you are passing in to the `createOrder` mutation is not set up in Toggle yet, or is incorrectly typed in. These references are site specific IDs that allow you to programmatically indicate back to Toggle which physical location this transaction is taking place in. We have an interface in Toggle where a user adds their sites/locations and specifies what the EPOS reference is for each one as they do so. For example: ![Toggle sites](http://eflyers.powertext.co.uk/toggle/support-assets/sites.png) #### The card number generated isn't the one provided If you create an order for a card and provide a card number, but the generated card number returned isn't the one you provided, check to make sure your Toggle account is set to use Magnetic Stripe cards under [Settings > General](https://dashboard.mytoggle.io/settings/general). # Balance check To check a card balance, pass in the `card_reference` to the `Cards` query. {% tabs %} {% tab title="API call" %} ```graphql query Cards { Cards(card_reference: "6301190004871637839") { data { card_reference balance card_alias_card_reference initial_balance product_name created_at used expiry_time validity_start_time } } } ``` {% endtab %} {% endtabs %} ### If no cards are found If no cards are found for your query, the API will respond with blank JSON for “Data”: ```javascript { "data": { "Cards": { "data": [] } }, "extensions": { "cost": { "actualQueryCost": 16, "throttleStatus": { "maximumAvailable": 8000, "currentlyAvailable": 7986 } } } } ``` # Redemptions & top-ups The `createBalanceAdjustment` mutation handles all balance adjustment against an existing card. A line item represents the balance adjustment action that took place and links it with the transaction responsible for the causing the balance adjustment. To create a balance adjustment for a card in Toggle, make a mutation request to `createBalanceAdjustment`. ### Redemptions (debit a gift card) To make a redemption adjustment, you can pass a negative value, e.g. “-100”. {% tabs %} {% tab title="API call " %} ```graphql mutation CreateBalanceAdjustment { createBalanceAdjustment( currency: "GBP" value: -1000 merchant_id: 26 unit_epos_reference: "2251799825000010" card_reference: "6301190019990640662" merchant_transaction_reference: "ABC-DEF-GHI-1234123-123-005" ) { id value LineItem { Card { id card_reference balance inital_balance created_at } } ValueSplit { tender discount } } } ``` {% endtab %} {% tab title="Response" %} ```json { "data": { "createBalanceAdjustment": { "id": 988008, "value": -10, "LineItem": { "Card": { "id": 529113, "card_reference": "6301190019990640662", "balance": 80, "initial_balance": 1000, "created_at": "2021-06-05 16:19:52" } }, "ValueSplit": { "tender": 800, "discount": 200 } } } } ``` {% endtab %} {% endtabs %} ### Tender vs Discount The API response we send back after a redemption will tell you whether to treat it as a discount (money-off, reducing sales tax/VAT) or as tender (treat the same as cash). In some cases, a redemption could be a mixture of discount and tender. ```javascript "ValueSplit": { "tender": 800, // £8 tender "discount": 200 // £2 discount } ``` We request that these values are handled different on payment, so that discount value is a Discount payment type on redemption to aid with VAT reporting. More details can be found [here](https://developers.usetoggle.com/key-concepts/overview/tender-vs-discount) ### Top-ups (credit a gift card) For a top-up, simply pass a positive value to the `createBalanceAdjustment` mutation. Examples can be found [here](/basics/redeem-a-card). # Reversing an order If a card has been created in error, you can reverse the transaction that created it. This may or may not be relevant depending if a card cancellation is a requirement on your particular integration. You can view how to perform a `createReversal` - See [Reversals](/reversals). # Guest gratuity # Overview Integrating with Toggle can prove very useful for guest relationship management software, feedback platforms, or any other platform where issuing gratuity pre-paid gift cards is a requirement. Some very simple API calls will allow your platform to issue gratuity vouchers via Toggle. Toggle will act as your card processor, keeping track of balances, discounts and redemptions. # Accreditation For approved partner integrations, you will need to complete our accreditation process. ### Accreditation test cases You will be asked to complete a series of test cases to ensure all use-cases have been met. Here is a sample list of test cases: 1. To test successful API authorisation 2. To test failed API authorisation with incorrect username/password 3. To test failed API request due to invalid or expired token 4. To test a successful creation of a new card 5. To test a failed order creation, with an invalid merchant\_id 6. To test a failed order creation, with invalid or missing product\_id 7. To test a failed order creation, with invalid or missing currency 8. To test a failed order creation, with invalid or missing sales\_channel\_id 9. To test a failed order creation, with invalid or missing fulfilment\_method\_id 10. To test a successful reversal of a card creation 11. To test a failed reversal due to missing or invalid line\_item\_id # Configuration variables Your application will need to keep a configuration of variables to use for each distinct Toggle account, These are summarised below. | `sales_channel_id` | For POS integrations, use `7` as the sales\_channel\_id when creating orders – this is a permanent ID used across all accounts for guest gratuity. | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fulfilment_method_id` | Used when creating orders, this can always be configured as either `1` (sends an Email from Toggle) or `8` which doesn't send an email. | | `currency_id` | Default to `1` (£ sterling), but leave this as something that can be configured as well, this will ensure the integration is future-proofed to handle other currency IDs in future. | | `account_id` | `account_id` will be manually configured, we will provide this to you each time a new account is configured. Email to request your account\_id. | | `merchant_id` | This identifies you as an an approved merchant on our platform. Email to request this. | | `unit_epos_reference` | This refers to the unique site location, passed to Toggle so its knows the location where the transaction was made. This needs to be matched with the configured EPOS references in each Toggle customer's account. If your transactions don't relate to a particular site, you will need a "head office" location reference on the Toggle account to use. [See here for more information](http://academy.usetoggle.com/en/articles/2892479-setting-up-toggle-for-multiple-sites). | | `merchant_transaction_reference` | Each order for a card should be related back to a unique transaction reference generated by your system. You should generate one (alphanumeric) and pass this to our API when handling transactions. | | `discount_type_id` | A discount type of `1` is a general-use FOC type so use this one if in doubt, though we also have other types available; for example `3` is for discounts for promotions. | # Creating a card To create an order in Toggle, make a mutation request to `createOrder`. The typical use cases for this journey are; * Toggle fulfils * Partner generates a gift card, and fulfils to the guest {% tabs %} {% tab title="Toggle fulfils" %} If you would like Toggle to fulfil the email to the guest, then you will need to ensure that; * `fulfilment_method_id` = 1 * `fulfilment_email` = guest to receive gift card ```graphql mutation CreateOrder { createOrder( account_id: 1 currency: "GBP" merchant_id: 24 group_fulfilment: false auto_fulfil_group_fulfilment: true merchant_transaction_reference: "912321-2139433213-12323421_26062021" total: 0 sales_channel_id: 3 note: "Guest had a bad experience, £10 offered" order_items: [ { product_id: 3532 custom_price_modifier_value: 5000 fulfilment_method_id: 1 generate_card_reference: true fulfilment_email: "anthony.moore+receipient@airship.co.uk" discounts: [{ discount_type_id: 1 value: 5000 }] } ] ) { id, LineItems{ id Card{ id card_reference pin balance expiry_time card_alias_card_reference product_name } } } } ``` {% endtab %} {% tab title="Partner fulfils" %} If you would like to fulfil the email to the guest, then you will need to ensure that; * `fulfilment_method_id` = 8 The card reference can be specified to return in the response, which can then be passed onto the guest. ```graphql mutation CreateOrder { createOrder( account_id: 1 currency: "GBP" merchant_id: 24 group_fulfilment: false auto_fulfil_group_fulfilment: true merchant_transaction_reference: "912321-2139433213-12323421_26062021" total: 0 sales_channel_id: 3 note: "Guest had a bad experience, £10 offered" order_items: [ { product_id: 3532 custom_price_modifier_value: 5000 fulfilment_method_id: 8 generate_card_reference: true discounts: [{ discount_type_id: 1 value: 5000 }] } ] ) { id, LineItems{ id Card{ id card_reference pin balance expiry_time card_alias_card_reference product_name } } } } ``` {% endtab %} {% endtabs %} ### What contact details should I use? The `receipt_contact` details are the "purchaser" of the card. So for automated guest gratuity cards, you could either hard-code these to a system level address or you could use the currently logged in user to your own platform, if you have such a thing or... you can leave the `receipt_contact` details out of your mutation. If the receipt\_contact is added, and the account has 'Send receipt emails' enabled - then this email address will receive confirmation whenever an order is added against them (note, this is just a receipt and not the actual gift card) ### What merchant ID to I use? Merchant IDs are issued to approved partner integrations for auditing and reporting purposes. If you have not been issued with a `merchant_id`, you may remove this field from your query. ### What product ID should I use? All orders in Toggle are linked to a product. This would enable you to create a menu of product options to choose from when selling a gift card or experience. To retrieve a list of products for an account: {% tabs %} {% tab title="APi query" %} ```graphql query($account_id:Int!) { Products(account_id:$account_id) { id name } } ``` {% endtab %} {% tab title="Variables" %} ```javascript { "data": { "Products": [ { "id": 244, "name": "In-Store Gift" }, { "id": 245, "name": "Summer Promotion" } ] } } ``` {% endtab %} {% endtabs %} Alternatively, we do have a default product on every account which you can use if you wish to simply sell a single gift card product type and avoid the extra overhead of creating a menu of product options to choose from. To retrieve the default product ID, use the same query as above and find a product called "In-store Gift". This Product ID will be unique per customer/client account, but you only need to retrieve and configure this id a single time as it will not change for an account once that account exists. ### Price modifier vs custom price modifiers The `price_modifier_id` relates to the particular price option for this card. e.g. a pre-defined list of denominations. Products can also be set to allow a "custom price modifier" on a product-by-product basis. In such cases, you can pass in the value of the card using: ```javascript "custom_price_modifier_value": 2500 ``` instead of using a `price_modifier_id`. ### Total vs discounts For Guest Gratuity cards, the `total` would always typically be `0` as there is nothing to pay. For the discount, this is passed in with a `discount_type_id` and value. A discount type of `1` is a general-use FOC type, though we also have other types available. For example `3` is for discounts for promotions. These different configuration variables are all to designed to aid book-keepers with reporting on card sales and discounts. ### What does auto\_fulfil\_group\_fulfilment do? This variable automatically marks your order as 'fulfilled' in Toggle (e.g. sent and dispatched). If, for some reason, you wanted to leave an order as open, and mark as fulfilled later, you could do this with some subsequent API calls. However, for your use-case, we recommend using this to automatically close off all orders you create as fulfilled. # Reversing an order If a card has been created in error, you can reverse the transaction that created it. This may or may not be relevant depending if a card cancellation is a requirement on your particular integration. You can view how to perform a `createReversal` - See [Reversals](/reversals). # CRM # Overview If you are have a CRM or other customer database into which you want to automatically store Toggle customer details, you can retrieve this data using a mixture of our webhooks and API. For real-time data, we recommend using webhooks. However, you may want to also use our API to retrieve additional data or to perform one-time syncs for historic data. # Historic data via GraphQL Where as it is possible to get some data from our API for historic Customers, Cards or Transactions - its not always optimal due to the volume / Throttling limits. Typically we would recommend using data exports to get historic data and then enabling real time web hooks to keep the data in sync going forward. ### Get Transactions You can get a list of historic orders, and narrow down by created\_at. This will return all orders on a specific day This call also supports [pagination](/graphql/pagination-throttling), so you can easily chunk up the requests as needed. ```graphql { Orders( page: 1 limit: 10 created_at: "2025-02-03 00:00:00" ) { data { LineItems { id created_at Transaction { merchant_transaction_reference } Card { card_reference balance expiry_time } } } } } ``` ### Get Orders You can get all historic orders from the API. The limitations to this request is that you cannot specific a date, and the results are sorted by 'Card ID' - so new transactions can appear at any page within the results rather than at the end. ```graphql { LineItems( page: 1 limit: 10 ) { data { id, created_at, value, LineItemType { name, } Transaction{ merchant_transaction_reference, Merchant { name } Unit { name id } } Card { id, Account{ name, id } card_reference, pin, balance, expiry_time, card_alias_card_reference product_name } } } } ``` # Real time data via webhooks To retrieve real-time data, use our webhooks service. # Custom Web shops ``` ``` # Overview Using our APIs, its possible to Sell gift cards in a custom Web Shop or via an online eCommerce site (i.e. Shopify). This is typically used when the client doesn't want to use the Toggle web shop, but incorporate gift card sales into their existing only shop and have them activated in Toggle - which takes advantage of our other integrations for redemption. The main requests required for this are; * Authorisation * Create a card (Digital / Postal) * Reversals Postal adds an additional complication to the integration, and the client needs to have the relevant commercials in place & any postage costs incurred by our fulfilment provider will be passed onto the client. # Accreditation There is no formal accreditation for this, as these implementations are usually bespoke for a specific client and there is no recommended route for integration. Our support team can be on hand to help with any guidance on setup and API use for this, but we would suggest that you do extensive testing around Postage and physical delivery if that is supported by the integration. # Configuration variables Your application will need to keep a configuration of variables to use for each distinct Toggle account (e.g. for each of our mutual shared customers/clients). These are summarised below. | Variable | Description | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sales_channel_id` | For POS integrations, use `3` as the sales\_channel\_id when creating orders – this is a permanent ID used across all accounts for in-store transactions. | | `fulfilment_method_id` |

If you issue digital cards from your application, and would like Toggle to send the guest the gift card - this would be 1 (Email)

If you issue digital cards from your application, and would like Toggle to send the guest the gift card - this would be 2 (Postal)

If you want to issue the card from your application, this would be 8 (3rd Party)

| | `currency` | Default to `GBP` (£ sterling), but leave this as something that can be configured as well, this will ensure the integration is future-proofed to handle other currency IDs in future. | | `account_id` | `account_id` will be manually configured, and will be provided during onboarding of a new mutual customer. Email to request an `account_id`. | | `merchant_id` | This identifies you as an an approved merchant on our platform. Email to request this. | | `unit_epos_reference` | This refers to the unique site location, passed to Toggle so its knows the location where the transaction was made. This needs to be matched with the configured EPOS references in each Toggle customer's account. If your transactions don't relate to a particular site, you will need a "head office" location reference on the Toggle account to use. [See here for more information](http://academy.usetoggle.com/en/articles/2892479-setting-up-toggle-for-multiple-sites). | | `merchant_transaction_reference` | This refers to the unique reference created by the your platform when the transaction is made. You will generate and pass this to our API when handling transactions. | # Create a card To create an order in Toggle, make a mutation request to `createOrder`. The typical use cases for this type of integration are; * Digital sales - Toggle fulfils * Digital sales - Partner fulfils * Physical Sales - Toggles warehouse fulfils {% tabs %} {% tab title="Digital - Toggle fulfils" %} If you would like Toggle to fulfil the email to the guest, then you will need to ensure that; * `fulfilment_method_id` = 1 * `fulfilment_email` = guest to receive gift card ```graphql mutation CreateOrder { createOrder( account_id: 1 currency: "GBP" merchant_id: 24 group_fulfilment: true auto_fulfil_group_fulfilment: false group_fulfilment_postage_category_id: 576 group_fulfilment_address: { name: "John Smith" address_line_1: "123 made up street" address_line_2: "Tixall" town_city: "Sheffield" postcode: "S01 1AA" } merchant_transaction_reference: "abc-def-123-123-423-aaasdf105" unit_epos_reference: "2251799825000010" total: 6000 sales_channel_id: 3 order_items: [ { product_id: 3983 custom_price_modifier_value: 5000 fulfilment_method_id: 2 generate_card_reference: false message: "This is my personal message!" } ] receipt_contact: { email: "john.smith+purchaser@usetoggle.co.uk" first_name: "john" last_name: "smith" } ) { id, LineItems{ id Card{ id card_reference pin balance expiry_time card_alias_card_reference product_name } } } } ``` {% endtab %} {% tab title="Digital - Partner fulfils" %} If you would like to fulfil the email to the guest, then you will need to ensure that; * `fulfilment_method_id` = 8 The card reference can be specified to return in the response, which can then be passed onto the guest. ```graphql mutation CreateOrder { createOrder( account_id: 1 currency: "GBP" merchant_id: 24 group_fulfilment: false auto_fulfil_group_fulfilment: true merchant_transaction_reference: "912321-2139433213-12323421_26062021" total: 0 sales_channel_id: 3 note: "Guest had a terrible experience, £10 offered" order_items: [ { product_id: 3532 custom_price_modifier_value: 5000 fulfilment_method_id: 8 generate_card_reference: true message: "This is my personal message!" discounts: [{ discount_type_id: 1 value: 5000 }] } ] ) { id, LineItems{ id Card{ id card_reference pin balance expiry_time card_alias_card_reference product_name } } } } ``` {% endtab %} {% tab title="Physical" %} If you would like Toggle to fulfil the email to the guest, then you will need to ensure that; * `fulfilment_method_id` = 2 * `auto_group_fulfilment` = false (Physical orders are fulfiled by our warehouse, so this is set to true by them once the card is sent) * `group_fulfilment_postage_cagegory_id` = This can be obtained from the get Products call, as different products can have different postage options * `group_fulfilment_address` = The address which the gift card should be delivered to * `total` = This needs to be the total value of the order (`custom_price_modifier_value` + `discount` if applicable + postage amount) * `receipt_contact` = optional, if you want Toggle to send a confirmation to the guest on purchase ```graphql mutation CreateOrder { createOrder( account_id: 1 currency: "GBP" merchant_id: 24 group_fulfilment: true auto_fulfil_group_fulfilment: false group_fulfilment_postage_category_id: 576 group_fulfilment_address: { name: "Anthony Moore" address_line_1: "123 made up street" address_line_2: "Tixall" town_city: "Stone" postcode: "ST01 1AA" } merchant_transaction_reference: "abc-def-123-123-423-aaasdf105" total: 6000 sales_channel_id: 3 order_items: [ { product_id: 3983 custom_price_modifier_value: 5000 fulfilment_method_id: 2 generate_card_reference: false message: "This is my personal message!" } ] receipt_contact: { email: "anthony.moore+purchaser@airship.co.uk" first_name: "Anthony" last_name: "Moore" } ) { id, LineItems{ id Card{ id card_reference pin balance expiry_time card_alias_card_reference product_name } } } } ``` {% endtab %} {% endtabs %} # Reversing an order If a card has been created in error, you can reverse the transaction that created it. This may or may not be relevant depending if a card cancellation is a requirement on your particular integration. You can view how to perform a `createReversal` - See [Reversals](/reversals).