> For the complete documentation index, see [llms.txt](https://developer.magtek.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.magtek.com/services/magensa/mppg-unigate/getting-started-with-unigate.md).

# Getting Started with Unigate

This guide takes you from your Pilot credentials to your first approved test transaction on Unigate, Magensa's API for card-present and card-not-present payments through MPPG v5 or later. You'll set up Postman, build the `Authorization` header Unigate requires, run a sample EMV sale, and learn which response values to keep for later requests.

{% hint style="info" %}
**New to Unigate?** Read the [<mark style="color:red;">**MPPG/Unigate**</mark>](https://developer.magtek.com/services/magensa/mppg-unigate) overview first for what Unigate does and when to use it.&#x20;
{% endhint %}

## Before you begin

You need:

* **A Postman account.** The sample requests are published as a Postman collection. Sign up at [<mark style="color:red;">**postman.com**</mark>](https://www.postman.com/) if you don't have one.
* **Your Unigate Onboarding Worksheet.** It lists your Pilot `CustomerCode`, `Username`, and `Password`, plus the Base64-encoded version of those credentials.
* **Familiarity with REST APIs** and the basics of payment processing.
* **A MagTek card reader (optional for this guide).** The samples include a working ARQC, so you can run your first transaction without one. You'll need a reader before your integration is complete..

## Pilot and Production

Unigate has two environments, and each has its own credentials.

<table data-header-hidden><thead><tr><th width="140.18182373046875"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Environment</strong></td><td><strong>Use it for</strong></td><td><strong>Credentials</strong></td></tr><tr><td><strong>Pilot</strong></td><td>Development and testing. Requests go to processor test systems, so nothing is charged.</td><td>From your Onboarding Worksheet, which includes the pre-encoded Base64 value.</td></tr><tr><td><strong>Production</strong></td><td>Live transactions.</td><td>Issued separately. You must build the <code>Authorization</code> header yourself.</td></tr></tbody></table>

{% hint style="info" %}
**Building Tap to Pay on iPhone?** Apps with a development entitlement use the Magensa **SANDBOX** environment, and apps with a production entitlement use **PRODUCTION**. See [<mark style="color:red;">**Tap to Pay on iPhone API**</mark>](https://developer.magtek.com/products/card-readers/magtek-virtual-reader-ios-sdk/tap-to-pay-on-iphone-api)
{% endhint %}

#### Step 1: Copy the collection to Postman

1. Sign in to Postman.
2. Open the [<mark style="color:red;">**Unigate API**</mark>](https://unigate.developer.magtek.com/#intro) collection.
3. Select **Run in Postman** in the top right of the page. The button only appears when you're signed in.
4. Choose the workspace to copy the collection into.

#### Step 2: Build the Authorization header

Unigate authenticates every request with HTTP Basic Auth in the `Authorization` header. Unigate's credential format combines three values instead of the usual two:

1. Join your `CustomerCode` and `Username` with a forward slash (`/`).
2. Add a colon (`:`) and your `Password`.
3. Base64-encode the resulting string.
4. Put `Basic` and a space in front of the encoded string.

**Worked example**

<table data-header-hidden><thead><tr><th width="203.54541015625"></th><th></th></tr></thead><tbody><tr><td><strong>Step</strong></td><td><strong>Value</strong></td></tr><tr><td>CustomerCode</td><td><code>CUSTOMER000</code></td></tr><tr><td>Username</td><td><code>MAGTEST000</code></td></tr><tr><td>Password</td><td><code>123456789</code></td></tr><tr><td>Combined string</td><td><code>CUSTOMER000/MAGTEST000:123456789</code></td></tr><tr><td>Base64 encoded</td><td><code>Q1VTVE9NRVIwMDAvTUFHVEVTVDAwMDoxMjM0NTY3ODk=</code></td></tr><tr><td><strong>Authorization header</strong></td><td><code>Basic Q1VTVE9NRVIwMDAvTUFHVEVTVDAwMDoxMjM0NTY3ODk=</code></td></tr></tbody></table>

For Pilot, you can copy the encoded value straight from your Onboarding Worksheet. For Production, generate it in code:

### Python

```python
import base64

customer_code = "CUSTOMER000"
username = "MAGTEST000"
password = "123456789"

raw = f"{customer_code}/{username}:{password}"
auth_header = "Basic " + base64.b64encode(raw.encode("utf-8")).decode("ascii")
```

### Node.js

```javascript
const customerCode = "CUSTOMER000";
const username = "MAGTEST000";
const password = "123456789";

const raw = `${customerCode}/${username}:${password}`;
const authHeader = "Basic " + Buffer.from(raw, "utf8").toString("base64");
```

### C\#

```csharp
using System;
using System.Text;

string customerCode = "CUSTOMER000";
string username = "MAGTEST000";
string password = "123456789";

string raw = $"{customerCode}/{username}:{password}";
string authHeader = "Basic " + Convert.ToBase64String(Encoding.UTF8.GetBytes(raw));
```

### Shell

```bash
echo "Basic $(printf '%s' 'CUSTOMER000/MAGTEST000:123456789' | base64)"
```

{% hint style="warning" %}
**WARNING: Base64 is encoding, not encryption.** Anyone who sees the header can decode your password. Send requests only over HTTPS, keep credentials out of source control, and never log the header.
{% endhint %}

#### Step 3: Save your credentials at the collection level

Set your credentials once on the collection so every sample request inherits them:

1. In Postman, select the Unigate collection and open the **Authorization** tab.
2. Set **Auth Type** to **Basic Auth**.
3. Enter `CustomerCode/Username` as the username (for example, `CUSTOMER000/MAGTEST000`) and your password as the password. Postman builds the encoded header for you.
4. Save the collection.

Leave each request's authorization set to **Inherit auth from parent** (the default). If a request fails to authenticate, check that it hasn't been changed.

#### Step 4: Run your first EMV sale

1. In the collection, open the **Transaction › EMV** folder ([<mark style="color:red;">**EMV**</mark>](https://unigate.developer.magtek.com/#d7dba37e-654b-4ee0-9d80-01e1e76c33e3)).
2. Open **EMV ARQC Sale**. **EMV ARQC Authorize** also works as a starting point.
3. Select **Send**.

The request already contains a sample ARQC, so it runs against your Pilot account in real time without a card reader.

#### Step 5: Read the response

A Unigate response contains three kinds of data:

| **Data**                        | **What it's for**                                                                                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Standardized Magensa fields** | Consistent values across every processor. For example, `isTransactionApproved` tells you whether the processor approved the transaction, whatever that processor calls "approved." |
| **Normalized processor fields** | Processor fields renamed to common keys. For example, Fiserv's `ReturnCode` becomes `processorStatusCode`, and TSYS's `hostReferenceNumber` becomes `processorReference`.          |
| **Raw processor fields**        | The processor's original values, always included so no data is lost.                                                                                                               |

Check `isTransactionApproved` rather than parsing processor-specific status values. Processors report approval differently: Fiserv returns `"StatusCode": "OK"`, TSYS returns `status: "PASS"`, and Worldpay returns `TransactionStatus: "Approved"`. Amount formats (cents vs. dollars) and date formats also vary. For examples from each processor, see [<mark style="color:red;">**Processor Responses**</mark>](https://unigate.developer.magtek.com/#processor-responses)<mark style="color:red;">.</mark>

{% hint style="info" %}
**Save the `MagTranID`.** Record the full response from every Transaction request. To Capture, Tip Adjust, Refund, or Void a transaction later, you send a ReferenceTransaction request that uses the original `MagTranID`.&#x20;
{% endhint %}

#### Step 6: Test with your own MagTek reader

The sample ARQC proves your credentials and request format work. Before your integration is complete, you must send an ARQC that your own MagTek reader generated.

1. Connect your test reader. See [<mark style="color:red;">**Connection Basics**</mark>](https://developer.magtek.com/get-started/connection-basics).
2. Run an EMV transaction on the reader with a test card. See [<mark style="color:red;">**Your First Transaction**</mark>](https://developer.magtek.com/get-started/your-first-transaction).
3. In **EMV ARQC Sale**, replace the sample ARQC (also called the Authorization Request) with your reader's ARQC output. For the format of that data, see [<mark style="color:red;">**EMV ARQC Type**</mark>](https://developer.magtek.com/api-and-command-reference/dynafamily-programmers-manual/data-types-and-shared-tlv-data-objects/emv-arqc-type).
4. Send the request. Pilot uses test systems, so nothing is charged.

To see a reader and Unigate working together in a browser first, try the [<mark style="color:red;">**MMS Unigate Demo**</mark>](https://rms.magensa.net/Test/demo/mmsUnigateDemo.html). For help getting started with readers, see the [<mark style="color:red;">**RMS reader quickstart**</mark>](https://rms.magensa.net/TEST/Demo/).

## Before you go to Production

* **Check your processor's var sheet.** Some processors have non-standard requirements, which they list on the var sheet they issue to you.
* **Build the Production header in code** as shown in **Step 2**. Production credentials don't come pre-encoded.
* **Contact your assigned solutions architect** for processor-specific inputs and outputs, advanced request fields, or anything this guide doesn't cover.

## Next steps

| **Topic**                                                                                                                                              | **What you'll learn**                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| [<mark style="color:red;">**Transactions and Reference Transactions**</mark>](https://unigate.developer.magtek.com/#overview)                          | How initial requests (Sale, Authorize) relate to follow-up actions (Capture, Tip Adjust, Refund, Void). |
| [<mark style="color:red;">**Normalized Processor Response Fields**</mark>](https://unigate.developer.magtek.com/#normalized-processor-response-fields) | How Unigate maps processor-specific fields to common keys.                                              |
| [<mark style="color:red;">**Unigate API Reference**</mark>](https://developer.magtek.com/services/magensa/mppg-unigate)                                | Every Transaction and ReferenceTransaction request, with links into the Postman collection.             |
| [<mark style="color:red;">**Web-based Demos**</mark>](https://developer.magtek.com/services/magensa/mppg-unigate)                                      | Browser demos of Unigate with and without MagTek readers.                                               |

## Need More Help?

{% hint style="info" %}
**Need Help?**

For additional support, please contact MagTek Support:

**Technical Support:**

* 📧 **Email:** [support@magtek.com](mailto:support@magtek.com?subject=Support%20Request)
* 📞 **Phone:** 1-562-546-6800 (US)
* 🕐 **Hours:** Monday-Friday, 5:30 AM - 5:00 PM PST

**Online Resources:**

* 🌐 **Support Portal:** developer.magtek.com

**Documentation Feedback:**

Help us improve this documentation! [feedback@magtek.com](mailto:feedback@magtek.com?subject=Feedback)
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.magtek.com/services/magensa/mppg-unigate/getting-started-with-unigate.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.