# Payflow Gateway Magtek Parameters (/api/nvp-soap/payflow/integration-guide/magtek)



MagTek products for both merchants and consumers provide added security to payment transactions. For merchants, MagTek's MagneSafe card readers encrypt payment card data when the card is swiped. For consumers, MagTek has a subscription based service named Qwick Codes. Consumers can use Qwick Codes instead of their payment card details to purchase goods and services.

> **Note:** **Note:** You must have a MagneSafe card reader or the required Qwick Code information to use the MagTek specific parameters described in this appendix. Please contact MagTek directly for more information.

* [MagTek MagneSafe Secure Card Readers and Qwick Codes](#magtek-magnesafe-secure-card-readers-and-qwick-codes)
* [Passing Encrypted Card Swipe Data and Qwick Codes to the Payflow Gateway](#passing-encrypted-card-swipe-data-and-qwick-codes-to-the-payflow-gateway)
* [Parameters for Encrypted Card Swipe Transactions](#parameters-for-encrypted-card-swipe-transactions)
* [Parameters for MagTek Qwick Code PCode Transactions](#parameters-for-magtek-qwick-code---pcode---transactions)
* [MagTek Error Codes and Messages](#magtek-error-codes-and-messages)

## MagTek MagneSafe Secure Card Readers and Qwick Codes [#magtek-magnesafe-secure-card-readers-and-qwick-codes]

### MagneSafe Secure Card Reader Authenticators [#magnesafe-secure-card-reader-authenticators]

MagTek's MagneSafe ™  secure card readers encrypt payment card track data such as the credit card account number and the expiration date. MagTek's Secure Card Reader Authenticators (SCRAs) capture data with a single swipe and can deliver dynamic card authentication, data encryption, tokenization, and device/host authentication to help protect merchants and their customers from identity theft and card fraud. MagTek's MagneSafe SCRAs can also identify counterfeit cards.

**What is MagneSafe?** The MagneSafe Security Architecture (MSA) is MagTek's digital identification and authentication architecture that can safeguard consumers and their personal data. MSA leverages strong encryption, secure tokenization, counterfeit detection, tamper recognition, data relevance and integrity, and dynamic digital transaction signatures to validate and protect the entire transaction.

The devices supported by MagTek's MagneSafe security and Magensa Services are:

* USB MSR: Dynamag.
* Insert MSR for Kiosks, ATMs, etc.:  MagneSafe I-65 for Chip Cards and MagStripe, PSeries MagneSafe for outdoors, Slim Seal MagneSafe.
* Mobile Readers: iDynamo for iOS, Bullet for Android, uDynamo for phones and tablets with audio jack port.
* PINPads: IPAD PINPad available as standard model and also with signature capture support.

### MagTek Qwick Codes [#magtek-qwick-codes]

MagTek offers a subscription based service to consumers named Qwick Codes. Instead of handing over plastic cards to store clerks or inserting them into unattended terminals like ATMs or gas pumps that may have been rigged with skimmers to steal card data, consumers can scan or type a Qwick Code from their smart phone or computer. The Qwick Code token is used instead to initiate a transaction whereby the merchant or ATM's processor can gather the actual card data on the back end of the transaction where it can be better secured and shielded from potential compromise. Qwick Code tokens are also known as Protection Codes or PCodes.

## Passing Encrypted Card Swipe Data and Qwick Codes to the Payflow Gateway [#passing-encrypted-card-swipe-data-and-qwick-codes-to-the-payflow-gateway]

The Payflow Gateway can process transactions for merchants who already have MagneSafe card readers or who accept MagTek Qwick Codes. You must have a MagneSafe card reader or the required Qwick Code information to use the MagTek specific parameters described below. Please contact MagTek directly for more information on obtaining the required card readers and codes.

When you pass MagneSafe encrypted card swipe data or a Qwick Code to the Payflow Gateway, Payflow will communicate directly with MagTek's Magensa servers to retrieve the payment card information. Payflow then passes the transaction data onto your merchant bank.

**Supported Transaction Types** Encrypted card swipe or Qwick Code (PCode) requests can be used with the following Payflow transaction types:

* Authorization (`TRXTYPE=A`)
* Credit (`TRXTYPE=C`)
* Delayed Capture (`TRXTYPE=D`)
* Sale (`TRXTYPE=S`)
* Void (`TRXTYPE=V`)

### Encrypted Card Swipe Payflow Example [#encrypted-card-swipe-payflow-example]

The purpose of this example is to show you how to format a request.You cannot use the values in this example for testing. You must have a MagneSafe card reader and test credit cards or live credit cards to send a request to the Payflow Gateway. Please contact MagTek for more information on obtaining card readers.

#### Request [#request]

This request contains regular Payflow parameters along with **required** MagTek parameters:

<div className="pl-[1.625rem]" />

```text lineNumbers
TRXTYPE=A&TENDER=C&VENDOR=MerchantUserID&PARTNER=PayPal&USER= UserIDIfAvailOrSameAsVendor&PWD=Pwd4Gateway&VERBOSITY=HIGH&CARDTYPE=1&SWIPEDECRHOST=MAGT&ENCTRACK2=82C69E600FF72FC1755509A76AD049E896A6EEA64D9BB2F203DF8AAD78265E90F4F8952A9AC03CFC&AMT=11.00&ENCMP=71AB2EE7A15887C36B8A23FED1CE7E6404D98119E24D15549E9B69AB6ABFB251C4A607D6A718B494449B506B7555BF8ED5FA4A9E2A6B814B&KSN=9011400B02AA0E00002B&MPSTATUS=3162209&ENCRYPTIONBLOCKTYPE=1&REGISTEREDBY=PayPal&MAGTEKCARDTYPE=1&DEVICESN=B02AA0E12151
```

See the [Encrypted Card Swipe Transactions - Request Parameters](#encrypted-card-swipe-transactions---request-parameters) for more information.

#### Response [#response]

If successful, the response will contain the standard Payflow response parameters for your transaction type:

<div className="pl-[1.625rem]" />

```text lineNumbers
RESULT=0&PNREF=V24A0A55E168&RESPMSG=Approved&AUTHCODE=098PNI00PN&HOSTCODE=A&VISACARDLEVEL=12
```

If you do not pass the required MagTek parameters, you will see: `RESULT=7` in the response along with a MagTek specific error message, such as:

`MAGTRESPONSE=H178-ENCTRACK2 has incorrect format.`

See the [Encrypted Card Swipe Transactions - Response Parameters](#encrypted-card-swipe-transactions---response-parameters) for more information.

### Qwick Code - PCode - Payflow Example [#qwick-code---pcode---payflow-example]

The purpose of this example is to show you how to format a request.You cannot use the values in this example for testing. You must have a MagTek test Qwick Code or live Qwick Codes to send a request to the Payflow Gateway. Please contact MagTek for more Qwick Code information.

#### Request [#request-1]

This request contains regular Payflow parameters along with **required** MagTek parameters:

<div className="pl-[1.625rem]" />

```text lineNumbers
TRXTYPE=A&TENDER=C&VENDOR=MerchantUserID&PARTNER=PayPal&USER=UserIDIfAvailOrSameAsVendor
&PWD=Pwd4Gateway&VERBOSITY=HIGH&AMT=18&SWIPEDECRHOST=MAGT&PCODE=23456789
&MERCHANTID=MerchantID123&MERCHANTNAME=MerchantName&PAN4=1234&BILLTOLASTNAME=Miller
&BILLTOZIP=95131&SHIPTOZIP=94089&AUTHVALUE1=1234&AUTHVALUE2=5678
&AUTHVALUE3=9012
```

See the [Qwick Code - PCode - Transaction Request Parameters](#qwick-code---pcode---transaction-request-parameters) for more information.

#### Response [#response-1]

If successful, the response will contain the standard Payflow response parameters for your transaction type:

<div className="pl-[1.625rem]" />

```text lineNumbers
RESULT=0&PNREF=V24A0A55E19C&RESPMSG=Approved&AUTHCODE=474PNI00PN&HOSTCODE=A
&VISACARDLEVEL=12
```

If you do not pass the required MagTek parameters, you will see: `RESULT=7` in the response along with a MagTek specific error message, such as:

`MAGTRESPONSE=H364-MERCHANTID has incorrect format`.

See the [Qwick Code - PCode - Transaction Response Parameters](#qwick-code---pcode---transaction-response-parameters) for more information.

## Parameters for Encrypted Card Swipe Transactions [#parameters-for-encrypted-card-swipe-transactions]

### Encrypted Card Swipe Transactions - Request Parameters [#encrypted-card-swipe-transactions---request-parameters]

| Field                 | Required | Description                                                                                                                                                                                                              | Data type                       | Length       |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | ------------ |
| `ENCMP`               | Required | Encrypted MagnePrint Information returned by a MagneSafe device when a card is swiped.                                                                                                                                   | String                          |              |
| `ENCRYPTIONBLOCKTYPE` | Required | The code which indicates what type of Encryption Block is used. 1=MagneSafe V4/V5 compatible 2TDEA-CBC Encryption, IV=0 Block contains data only.2=iPad V1 compatible 2TDEA-CBC Encryption Block contains header + data. | Integer                         | 1            |
| `ENCTRACK2`           | Required | Encrypted Track 2 information returned by a MagneSafe device when a card is swiped.                                                                                                                                      | String                          |              |
| `KSN`                 | Required | 20 character string returned by a MagneSafe device when a card is swiped.                                                                                                                                                | String                          | 20 char      |
| `MAGTEKCARDTYPE`      | Required | The code which indicates what type of Card Data Format is being submitted. 1=Encoding Format for Financial Transaction Cards (ISO 7811).                                                                                 | Integer                         |              |
| `MPSTATUS`            | Required | MagnePrint Status of Card Swipe. This is an alpha numeric string, returned by a MagneSafe device when a card is swiped.                                                                                                  |                                 |              |
| `REGISTEREDBY`        | Required | An alpha numeric entry between 1 and 20 characters long.                                                                                                                                                                 | Alphanumeric \[a-z]\[A-Z]\[0-9] | 1 to 20 char |
| `SWIPEDECRHOST`       | Required | `MAGT` is the only value that is accepted in the`SWIPEDECRHOST` parameter. If you pass a different value you will see `RESULT=7` and `MAGTRESPONSE` with an error message in the response.                               |                                 |              |
| `DEVICESN`            | Optional | The device serial number.                                                                                                                                                                                                | String                          |              |
| `ENCTRACK1`           | Optional | Encrypted Track 1 information returned by a MagneSafe device when a card is swiped.                                                                                                                                      | String                          |              |
| `ENCTRACK3`           | Optional | Encrypted Track 3 information returned by a MagneSafe device when a card is swiped.                                                                                                                                      | String                          |              |

### Encrypted Card Swipe Transactions - Response Parameters [#encrypted-card-swipe-transactions---response-parameters]

| Field          | Required                                                                                                             | Description | Data type                                                                            | Notes |
| -------------- | -------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ | ----- |
| `MAGTRESPONSE` | This parameter appears in the response if a data validation error occurs or if the MagTek processor throws an error. | String      | See the [Magtek error codes](#magtek-error-codes-and-messages) for more information. |       |

## Parameters for MagTek Qwick Code - PCode - Transactions [#parameters-for-magtek-qwick-code---pcode---transactions]

### Qwick Code - PCode - Transaction Request Parameters [#qwick-code---pcode---transaction-request-parameters]

| Field            | Required | Description                                                                        | Data type | Length                       |
| ---------------- | -------- | ---------------------------------------------------------------------------------- | --------- | ---------------------------- |
| `MERCHANTID`     | Required | Your Merchant ID or the Merchant ID of the merchant redeeming the Protection Code. | String    | 1 to 40 characters           |
| `PAN4`           | Required | The last four digits of the PAN / account number encoded in the card.              | String    | Four characters              |
| `PCODE`          | Required | The generated Protection Code.                                                     | String    | Eight character alphanumeric |
| `SWIPEDECRHOST`  | Required | `MAGT` is the only value currently accepted in the `SWIPEDECRHOST` parameter.      |           |                              |
| `AUTHVALUE1`     | Optional | Authentication Value 1 generated with the PCode.                                   | String    |                              |
| `AUTHVALUE2`     | Optional | Authentication Value 2 generated with the PCode.                                   | String    |                              |
| `AUTHVALUE3`     | Optional | Authentication Value 3 generated with the PCode.                                   | String    |                              |
| `BILLTOEMAIL`    | Optional | Purchaser's email address.                                                         | String    |                              |
| `BILLTOLASTNAME` | Optional | The last name of the card holder encoded in the card.                              | String    |                              |
| `BILLT0ZIP`      | Optional | The billing zip code.                                                              | String    |                              |
| `MAGTEKUSERNAME` | Optional | MagTek username.                                                                   | String    |                              |
| `MAGTEKPWD`      | Optional | MagTek password.                                                                   | String    |                              |
| `MERCHANTNAME`   | Optional |                                                                                    |           |                              |
| `SHIPTOZIP`      | Optional | Shipping zip code.                                                                 | String    |                              |

### Qwick Code - PCode - Transaction Response Parameters [#qwick-code---pcode---transaction-response-parameters]

| Field          | Description                                                                                                     | Data Type | Notes                                                                                      |
| -------------- | --------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
| `MAGTRESPONSE` | This only appears in the response if a data validation error occurs or if the MagTek processor throws an error. | String    | See the [Magtek error codes below](#magtek-error-codes-and-messages) for more information. |

## MagTek Error Codes and Messages [#magtek-error-codes-and-messages]

If an error occurs, one of the following error codes appear in the `MAGTRESPONSE` response parameter.

### Encrypted Card Swipe Transactions - Input Validation Error Codes [#encrypted-card-swipe-transactions---input-validation-error-codes]

| Error Message                              | Notes                    |
| ------------------------------------------ | ------------------------ |
| `H023 - REGISTEREDBY` has incorrect length |                          |
| `H024 - REGISTEREDBY` has incorrect format |                          |
| `H176 - ENCTRACK1` has incorrect format    |                          |
| `H177 - ENCTRACK1` has incorrect length    |                          |
| `H178 - ENCTRACK2` has incorrect format    |                          |
| `H179 - ENCTRACK2` has incorrect length    |                          |
| `H180 - ENCTRACK3` has incorrect format    |                          |
| `H181 - ENCTRACK3` has incorrect length    |                          |
| `H182 - ENCMP` has incorrect format        |                          |
| `H183 - ENCMP` has incorrect length        |                          |
| `H186 - KSN` has incorrect format          |                          |
| `H187 - KSN` has incorrect length          |                          |
| `H188 - MPSTATUS` has incorrect format     |                          |
| `H189 - MPSTATUS` has incorrect length     |                          |
| `H206` - Invalid `CARDTYPE`                | Invalid `MAGTEKCARDTYPE` |
| `H211` - Invalid `ENCRYPTIONBLOCKTYPE`     |                          |
| `H219` - Invalid `OUTPUTFORMATCODE`        |                          |
| `H251` - Invalid `DEVICESN`                |                          |

### Encrypted Card Swipe Transactions - Other Error Codes [#encrypted-card-swipe-transactions---other-error-codes]

| Error Message                           | Notes                                                                                                                                        |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `Y001` - No `PAN` Found in Track 2 Data |                                                                                                                                              |
| `Y003` - Device is not allowed          | MagTek maintains a list of registered Devices.                                                                                               |
| `Y093` - Invalid MagnePrint             | Error obtained while Scoring Transaction MagnePrint against a Reference MagnePrint made up of Zeros.                                         |
| `Y094` - Invalid MagnePrint             | "Negative 2 - Invalid Transaction CRC / `PAN`" Obtained when Scoring Transaction MagnePrint against a Reference MagnePrint Made up of Zeros. |
| `Y095` - Error Scoring Card             |                                                                                                                                              |
| `Y096` - Inactive MagnePrint Reference  | This occurs whenever the Card has an inactive MagnePrint Reference.                                                                          |
| `Y097` - Replay Prevented               | This occurs when the `DUKPT KSN` and Counter is replayed.                                                                                    |
| `Y098` - Problem with Reader Data       | This occurs if there is a problem while decrypting the Data.                                                                                 |

### Qwick Code - PCode - Transaction Input Validation Error Codes [#qwick-code---pcode---transaction-input-validation-error-codes]

| Error Message                            | Notes                              |
| ---------------------------------------- | ---------------------------------- |
| `H330 - PCODE` has incorrect length      |                                    |
| `H331 - PCODE` has incorrect format      |                                    |
| `H336 - EMAIL` has incorrect format      | `BILLTOEMAIL` has incorrect format |
| `H337 - EMAIL` has incorrect length      | `BILLTOEMAIL` has incorrect length |
| `H348 - BTZIP` has incorrect format      | `BILLTOZIP` has incorrect format   |
| `H349 - BTZIP` has incorrect length      | `BILLTOZIP` has incorrect length   |
| `H360 - STZIP` has incorrect format      | `SHIPTOZIP` has incorrect format   |
| `H361 - STZIP` has incorrect length      | `SHIPTOZIP` has incorrect length   |
| `H364 - MERCHANTID` has incorrect format |                                    |
| `H365 - MERCHANTID` has incorrect length |                                    |
| `H366` - Invalid `LASTNAME`              | Invalid `BILLTOLASTNAME`           |
| `H375 - PAN4` has incorrect length       |                                    |
| `H376 - PAN4` has incorrect format       |                                    |
| `H380` - Invalid `AUTHVALUE1`            |                                    |
| `H381` - Invalid `AUTHVALUE2`            |                                    |
| `H382` - Invalid `AUTHVALUE3`            |                                    |
| `H383` - Invalid `MERCHANTNAME`          |                                    |
| `H384` - Invalid `USERNAME`              | Invalid `MAGTEKUSERNAME`           |
| `H385` - Invalid `PASSWORD`              | Invalid `MAGTEKPWD`                |

### Qwick Code - PCode - Transaction Other Error Codes [#qwick-code---pcode---transaction-other-error-codes]

| Error Message                                       | Notes                                                        |
| --------------------------------------------------- | ------------------------------------------------------------ |
| `P021` - Invalid Protection Code - Not Found.       |                                                              |
| `P022` - Revoked Protection Code.                   | This Protection Code has already been revoked.               |
| `P028` - Expired Protection Code.                   |                                                              |
| `P031` - Last 4 of `PAN` mismatch.                  |                                                              |
| `P032` - `LASTNAME` mismatch.                       | `BILLTOLASTNAME` mismatch.                                   |
| `P033` - `MERCHANTID` is locked.                    |                                                              |
| `P034` - Protection Code can no longer be Redeemed. |                                                              |
| `P035` - `USERNAME` mismatch.                       | `MAGTEKUSERNAME` given does not match the one stored.        |
| `P036` - `PASSWORD` mismatch.                       | `MAGTEKPWD` given does not match the one stored.             |
| `P037` - `EMAIL` mismatch.                          | `BILLTOEMAIL` given does not match the one stored.           |
| `P038` - `BTZIP` mismatch.                          | `BILLTOZIP` given does not match the one stored.             |
| `P039` - `STZIP` mismatch.                          | `SHIPTOZIP` given does not match the one stored.             |
| `P040` - `AUTHVALUE1` mismatch.                     | `AUTHVALUE1` given does not match the one stored.            |
| `P041` - `AUTHVALUE2` mismatch.                     | `AUTHVALUE2` given does not match the one stored.            |
| `P042` - `AUTHVALUE3` mismatch.                     | `AUTHVALUE3` given does not match the one stored.            |
| `P098` - Problem with Reader Data                   | This occurs if there is a problem while decrypting the Data. |