Submit Credit Card Transactions

When using the Payflow SDK, plan how to implement credit card processing based on your business needs. Payflow SDK offers a core set of transaction parameters that all credit card processors use. This section describes how to submit a transaction for each transaction type supported.

Note: Some of the transaction types and features described in this chapter are not supported by all processors. Be sure to check with your processor for information on the specific functionality that is supported.

Obtain an Internet Merchant Account

To accept credit cards over the Internet, you need a special account called an Internet Merchant Account. If PayPal is your merchant bank, you do not need the Internet Merchant Account.

Your account provider or merchant (acquiring) bank works with a PayPal-supported credit card processor. Examples are First Data, TSYS Acquiring Solutions (formerly Vital Processing Services), and Paymentech. To accept live credit cards, provide details about your account to PayPal during the "Go Live" part of enrollment.

Note: An Internet Merchant Account is different type of merchant account. It has additional risks associated with card-not-present (e-commerce) transactions. It is different from a merchant account used for face-to-face/card-present (in-person) retail transactions . Obtain an Internet Merchant Account even if you already accept credit cards at your location.

To apply for an Internet Merchant Account, contact your merchant (acquiring) bank.

About Credit Card Processing

Credit card processing occurs in 2 steps -- a real-time authorization and a capture (settlement) of the funds that the card holder's issuing bank authorizes. You perform these 2 steps either as a single transaction or as two transactions, depending on your business model.

For an authorization, the server sends the transaction information to a credit card processor. The processor routes the transaction through the financial networks to the card holder's issuing bank. The issuing bank checks whether the card is valid. It evaluates whether sufficient credit exists, checks values such as address verification service and card security codes, and returns a response such as Approved, Declined, or Referral.

You receive the response a few seconds after you submit the transaction to the server. If the bank approves an authorization, it temporarily reserves the credit for the amount of the transaction to prepare to capture (fulfill) the transaction. The hold on funds typically lasts for about a 3-7 days.

Capturing a transaction actually transfers the funds to your bank. At least once a day, PayPal gathers all transactions flagged for settlement and sends them in a batch file to the processor. The processor then charges the issuing bank and transfers the funds to your bank. It typically takes a few days before the money is available in your account, depending on your bank.

Note: For card-not-present transactions, such as, online transactions, merchants are required to provide a service or ship goods before or on the same day the transaction is captured.

Credit Card Features

The Payflow SDK supports the following transaction types for credit card processing.

Note: Even though the Payflow Gateway does not charge fees for certain transactions, your processor, including PayPal as your merchant bank, may charge a fee.

Transaction Type Billable
Authorization Yes
Account Verification No *
Balance Inquiry No
Credit Yes
Delayed Capture No
Inquiry No
Sale Yes
Voice Authorization Yes
Void Yes

The Payflow SDK also supports the following credit card features:

  • Address verification service and card security code validation
  • Card-present (SWIPE) transactions
  • Partial authorizations for pre-paid cards
  • Purchasing card transactions
  • Reference transactions (also called tokenization)
  • Submit Soft Merchant information

Plan Your Gateway Integration

When designing your Gateway integration, evaluate whether to use:

  • A one-step or two-step transaction process:
    • One-step: Submit a sale transaction, which performs the authorization and (if successful) then flags the transaction for settlement.
    • Two-step: Perform an authorization-only transaction and then later perform a delayed capture transaction. The delayed capture transaction can be for the same amount as the original transaction or for a lower amount. (In the case of a split shipment, you can perform a delayed capture transaction for the initial shipment and a reference transaction for the final payment. According to card association rules, most physical goods merchants should use a two-step process, since settlement should occur when the merchant ships the goods. A two-step process is also useful for evaluating information in the response, such as whether the issuer verifies the billing address, and so on. Electronic goods merchants, who fulfill the order immediately, can use the one-step process. Check with your Internet Merchant Account provider for suggestions on the best method for you.
  • Risk management tools such as address verification service and card security code. For the address verification service, if the initial transaction submits the data, the issuer checks the street address and the zip code against the billing address on file for the consumer.
    • Card security code refers to a three- or four-digit number that appears on the back of most credit cards. On American Express, the number appears proceeding and to the right of the embossed card number. Card security code is known by other names, such as CVV2, depending on the type of card. If card security code data is submitted, the issuer can notify you whether the number matches the number assigned to the card. It may also be possible to implement additional safeguards yourself or to use a fraud service. You might want to discuss risk management with your Internet Merchant Account provider.
  • Your local database or PayPal Manager reports to store and manage the data. You may want to store shipping information in your system or you may prefer to send the information to PayPal with the transaction and report on it later.

Note: Consider whether and how to use COMMENT1 and COMMENT2 to help tie reports to your orders/customers or to report on other information about the transaction.

  • Other systems, such as order fulfillment, Customer Service, and so on for system integration. You may want to integrate your systems directly for capturing funds, issuing refunds/credits, and so on. Alternatively, you may prefer to perform these steps manually using PayPal Manager. Either way, PayPal recommends that you monitor transaction activity using PayPal Manager.
  • Your internet Merchant Acquirer practices to get the most advantageous rates.

Comply with E-commerce Indicator

Some processors support a software flag called E-commerce Indicator (ECI) that indicates that the associated transaction is an internet transaction. The Payflow SDK complies with ECI basic requirements for all supported processors.

If you use Buyer Authentication, the ECI values reflect the authentication status.

Handle Credit Card Type Information

The Payflow SDK does not check the credit card types that you are accepting. If a customer uses a card type you do not accept, the SDK responds with RESULT value 25, "Invalid host mapping," or the processor returns a message that the customer is not signed up for the card type. Optionally, you can provide your customer with a list of the card types that you accept (in a drop-down list or menu, for example).

To accept additional credit card types, contact your acquiring bank (holding your Internet Merchant Account) and ask them to add the card type to your account. Upon notification from your acquirer that you can start accepting the card type, add the card to your Payflow account through PayPal Manager. See PayPal Manager online help for details.

Note: American Express cards require explicit acceptance when PayPal is the processor. To accept American Express cards, go to the Profile Page in PayPal Manager and click American Express card acceptance.

Core Credit Card Parameters

All credit card processors accept the basic parameters described in the following table_ with one exception: the PayPal processor does not support SWIPE_.

Note: See PayPal Credit Card Transaction Request Parameters for the request parameters specific to the PayPal Processor.

Parameter Description
TENDER (Required) The method of payment. Values are:
- A = Automated clearinghouse (ACH)
- C = Credit card
- D = Pinless debit
- K = Telecheck
- P = PayPal
See the Payflow ACH Payment Service Guide for details on the ACH tender type.
TRXTYPE (Required) Indicates the type of transaction to perform. Values are:
- A = Authorization
- B = Balance Inquiry
- C = Credit (Refund)
- D = Delayed Capture
- F = Voice Authorization
- I = Inquiry
- K = Rate Lookup
- L = Data Upload
- N = Duplicate Transaction
Note: A type N transaction represents a duplicate transaction (version 4 SDK or HTTPS interface only) with a PNREF that is the same as the original. It appears only in the PayPal Manager user interface and never settles.
- S = Sale
- V = Void
ACCT (Required for credit cards) Credit card or purchase card number. For example, ACCT=5555555555554444. For the pin-less debit TENDER type, ACCT can be the bank account number.
Limitations: This value may not contain spaces, non-numeric characters, or dashes
EXPDATE (Required) Expiration date of the credit card. For example, 1215 represents December 2015.
Limitations: mmyy format
AMT (Required) Amount (Default: U.S. based currency).
Character length and limitations: numeric characters and a decimal only. The maximum length varies depending on your processor. Specify the exact amount to the cent using a decimal point (use 34.00 not 34). Do not include comma separators (use 1199.95 not 1,199.95). Your processor or Internet Merchant Account provider may stipulate a maximum amount.
Note: If your processor accepts non-decimal currencies, such as, Japanese Yen, include a decimal in the amount you pass to Payflow (use 100.00 not 100). Payflow removes the decimal portion before sending the value to the processor.
COMMENT1 (Optional) Merchant-defined value for reporting and auditing purposes.
Limitations: 128 alphanumeric characters
COMMENT2 (Optional) Merchant-defined value for reporting and auditing purposes.
Limitations: 128 alphanumeric characters
CVV2 (Optional) A code printed (not imprinted) on the back of a credit card. Used as partial assurance that the card is in the buyer's possession.
Limitations: 3 or 4 digits
RECURRING (Optional) Identifies the transaction as recurring. Value is:
- Y - Identifies the transaction as recurring.
- N - Does not identify the transaction as recurring (default).
This value does not activate the Payflow Recurring Billing Service API. If the RECURRING parameter value is Y in the original transaction, this value is ignored when forming credit, void, and force transactions. If you subscribe to the Payflow Fraud Protection Services:
- To avoid charging you to filter recurring transactions that you know are reliable, the fraud filters do not screen recurring transactions.
- To screen a prospective recurring customer, submit the transaction data on the PayPal Manager Manual Transactions page. The filters screen the transaction in the normal manner. If the transaction triggers a filter, follow the normal process to review the filter results.
Note: If your transaction is declined and the PAYMENTADVICECODE response parameter is supported by your processor, a PAYMENTADVICECODE value is returned representing the reason that the transaction was declined. Obtain the meaning of PAYMENTADVICECODE values from your acquiring bank.
Character length and limitations: 1 alpha character
SWIPE (Required for card-present transactions only) Used to pass the Track 1 or Track 2 data (card's magnetic stripe information) for card-present transactions. Include either Track 1 or Track 2 data, not both. If Track 1 is physically damaged, the point-of-sale (POS) application can send Track 2 data instead.
The track data includes the disallowed = (equal sign) character. To enable you to use the data, the SWIPE parameter must include a length tag specifying the number of characters in the track data. For this reason, in addition to passing the track data, the POS application must count the characters in the track data and pass that number. Length tags are described in Using Special Characters In Values.
Note: swipe(card-present transactions) are not supported by the PayPal processor.
Limitations: Alphanumeric and special characters
ORDERID (Optional) Checks for a duplicate order. If you pass ORDERID in a request and pass it again in the future, the response returns DUPLICATE=2 along with the ORDERID.
Note: Do not use ORDERID to catch duplicate orders processed within seconds of each other. Use ORDERID with Request ID to prevent duplicates as a result of processing or communication errors.
BILLTOFIRSTNAME (Optional) Card holder's first name.
Limitations: 30 alphanumeric characters
BILLTOLASTNAME (Optional but recommended) Card holder's last name.
Limitations: 30 alphanumeric characters
BILLTOSTREET (Optional) The card holder's street address (number and street name).
The address verification service verifies the STREET address.
Limitations: 30 alphanumeric characters
BILLTOSTREET2 (Optional) The second line of the card holder's street address.
The address verification service verifies the STREET address.
Limitations: 30 alphanumeric characters
BILLTOCITY (Optional) Bill-to city.
Limitations: 20-character string.
BILLTOSTATE (Optional) Bill-to state.
Limitations: 2-character string.
BILLTOZIP (Optional) Card holder's 5- to 9-digit zip (postal) code.
Limitations: 9 characters maximum. Do not use spaces, dashes, or non-numeric characters
BILLTOCOUNTRY (Optional) Bill-to country. The Payflow API accepts 3-digit numeric country codes. Refer to the ISO 3166-1 numeric country codes.
Limitations: 3-character country code.
SHIPTOFIRSTNAME (Optional) Ship-to first name.
Limitations: 30-character string.
SHIPTOLASTNAME (Optional) Ship-to last name.
Limitations: 30-character string.
SHIPTOSTREET (Optional) Ship-to street address.
Limitations: 30-character string.
SHIPTOCITY (Optional) Ship-to city.
Limitations: 20-character string.
SHIPTOSTATE (Optional) Ship-to state.
Limitations: 2-character string.
SHIPTOZIP (Optional) Ship-to postal code.
Limitations: 9-character string.
SHIPTOCOUNTRY (Optional) Ship-to country. The Payflow API accepts 3-digit numeric country codes. Refer to the ISO 3166-1 numeric country codes.
Limitations: 3-character country code.

Echo data

The ECHODATA field is a Payflow request parameter. Use this field if you would like some of your request field values echoed back to you in the response. The following ECHODATA field values can be used for POST or Silent Post transactions.

ECHODATA request field value Fields returned in the response
address Returns in the response the following billing and shipping fields if provided in the request:
- BILLTOFIRSTNAME
- BILLTOMIDDLENAME
- BILLTOLASTNAME
- BILLTOCOMPANY
- BILLTOSTREET
- BILLTOSTREET2
- BILLTOCITY
- BILLTOSTATE
- BILLTOZIP
- BILLTOCOUNTRY
- BILLTOEMAIL
- BILLTOPHONENUM
- SHIPTOFIRSTNAME
- SHIPTOMIDDLENAME
- SHIPTOLASTNAME
- SHIPTOCOMPANY
- SHIPTOSTREET
- SHIPTOSTREET2
- SHIPTOCITY
- SHIPTOSTATE
- SHIPTOZIP
- SHIPTOCOUNTRY
custdata Returns in the response the following fields if provided in the request:
- COMMENT1
- COMMENT2
- CURRENCY
- CUSTCODE
- CUSTREF
- EMAIL
- INVNUM
- ORDERID
- PONUM
- TRXTYPE
user Returns the fields USER1 through USER10 if provided in the request.

Submit Account Verifications

Account verifications, also known as zero-amount authorizations, are used for verifying the validity of customer credit card information. TRXTYPE=A is required for both account verifications and for normal authorization transactions; however, account verifications are different from normal authorizations in the following ways:

  • For account verifications, pass a zero AMT. If you pass any other amount, the transaction becomes a normal authorization that places a hold on the card holder's open-to-buy limit.
  • In account verifications, even if the RESULT value returned is 0 (Approved), the RESPMSG value returned is Verified instead of Approved.

Note: Payflow returns RESULT value 4, Invalid Amount, if the processor does not support account verifications.

See the Account Verifications Supported Credit Cards by Processor table for details.

When To Use Account Verifications

Use account verifications to validate account numbers and other authentication elements such as CVV2 and AVS.

Account verifications cannot be voided, captured, or refunded. Attempting to do so results in a declined transaction, RESULT=12.

A reference transaction can be based on a successful account verification transaction and used to charge the customer's verified account. See Submit Reference Transactions - Tokenization.

Required Account Verification Parameters

To complete an account verification, pass the following parameters:

Parameter Description
TRXTYPE (Required) Set to A.
Limitations: 1 alphanumeric character.
AMT (Required) Set to 0.
VERBOSITY (Required) Set to HIGH to obtain information about a partial authorization in the response.

Example Account Verification String

The following is an example of account verification:

TRXTYPE=A&TENDER=C&PARTNER=PayPal&USER=SuperUser&PWD=SuperUserPassword&AMT=0.00&ACCT=378282246310005
&EXPDATE=1215&INVNUM=PONUM1&VERBOSITY=HIGH&BILLTOZIP=95031

This is the response:

RESULT=0&PNREF=VFHA0FF8F27D&RESPMSG=Verified&AUTHCODE=667PNI&AVSADDR=X&AVSZIP=X&HOSTCODE=A&PROCAVS=U
&AMEXID=123456789012345&AMEXPOSDATA=123456789012&TRANSTIME=2011-01-11 18:42:01&AMT=0.00&ACCT=0005
&EXPDATE=1215&CARDTYPE=3&IAVS=X

Account Verifications Supported Credit Cards by Processor

The following table lists the credit cards for which each processor supports account verifications.

Processor name Amex Discover Mastercard Visa
American Express Y
Elavon Y Y Y Y
First Data Merchant Services (FDMS) Nashville Y Y Y Y
First Data Merchant Services (FDMS) North Y Y Y Y
First Data Merchant Services (FDMS) South Y Y Y Y
Global Payments Y Y Y Y
Heartland Payment Systems Y Y Y Y
Litle Y Y Y Y
Merchant e-Solutions Y Y Y Y
Moneris Solutions Y Y Y Y
Paymentech Salem Y Y Y Y
Paymentech Tampa Y Y Y Y
PayPal Y Y Y Y
PayPal Australia Y Y Y Y
TSYS Acquiring Solutions Y Y Y Y
Vantiv Y Y Y Y
WorldPay Y Y Y Y

Submit Authorization - Delayed Capture - Transactions

An authorization (TRXTYPE=A) transaction places a hold on the card holder's open-to-buy limit, lowering the card holder's limit by the amount of the transaction. It does not transfer funds.

Perform a delayed capture (TRXTYPE=D) transaction after an authorization to capture the original authorization amount. PayPal schedules the delayed capture for settlement during the next settlement period.

Because Visa and MasterCard regulations prohibit capturing credit card payments until the buyer receives the product or service, most processing networks implement an authorization followed by a delayed capture.

Note: PayPal Payments Advanced and Payflow Link merchants cannot submit authorization transactions unless they use the [hosted checkout pages](/docs/classic/payflow/integration-guide/configure-hosted-checkout/.

When to Use Authorization - Delayed Capture - Transactions

If your business does not provide immediate fulfillment of products or services, PayPal recommends that you use delayed capture processing. It enables you to capture credit card payments when you are ready to collect them.

Note: If you signed up for the PayPal processor with Fraud Protection Services, use delayed capture processing for all sale transactions.

If your business provides immediate fulfillment and you are not using the PayPal processor with Fraud Protection Services, you can use a simple sale transaction instead. For details, see Submit Reference Transactions - Tokenization.

Note: You are allowed to perform one delayed capture transaction per authorization transaction.

Required Authorization Transaction Parameters

To perform a delayed capture transaction, pass the following parameter:

Parameter Description
ORIGID (Required by some transaction types) ID of the original transaction referenced, or the value returned in the PNREF parameter in the original transaction; it appears as the Transaction ID in PayPal Manager reports.
Limitations: 12 case-sensitive alphanumeric characters.

Submit Balance Inquiry Transactions

Balance Inquiry (TRXTYPE=B) transactions are used to obtain the balance of a pre-paid card. This transaction type is different from a balance inquiry performed during an authorization transaction. However, both of these transaction types will return the balance in the BALAMT response parameter.

Note: Payflow returns RESULT value 3, Invalid Transaction Type, if the processor does not support balance inquiry.

Processing Platforms that support Balance Inquiry Transactions

The following processing platforms currently support pre-paid card balance inquiry transactions. This feature will be added for more processors in the near future. As more processors are added, this list will be updated accordingly.

  • WorldPay

Required Balance Inquiry Parameters

To perform a balance inquiry on a pre-paid card, pass the following parameters:

Parameter Description
TRXTYPE (Required) Set to B.
Limitations: 1 alphanumeric character.
EXPDATE (Required) Expiration date of the pre-paid card in the format MMYY. For example, 1215 represents December 2015.
VERBOSITY (Required) Set to HIGH to obtain information about a balance inquiry in the response.

Example Balance Inquiry Transaction String

The following is an example of a balance inquiry transaction:

TRXTYPE=B&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperUser
&PWD=SuperUserPassword&ACCT=5555555555554444&EXPDATE=1215&VERBOSITY=HIGH

This is the response:

RESULT=0&PNREF=ERRV0A005933&RESPMSG=Approved&AUTHCODE=467PNI&HOSTCODE=000
&TRANSTIME=2012-02-16 18:41:25&AMT=0.00&BALAMT=10.00&ACCT=4444&EXPDATE=1215&CARDTYPE=0

Submit Card Present - SWIPE - Transactions

The Payflow SDK supports card present transactions (face-to-face purchases).

Note: The PayPal processor does not support SWIPE (card-present) transactions.

Follow these guidelines to take advantage of the lower card-present transaction rate:

  • Contact your merchant account provider to make sure that they support card-present transactions.
  • Contact PayPal Customer Service to request them to set up your account properly for accepting and passing swipe data.
  • If you plan to process card-present as well as card-not-present transactions, set up 2 separate Gateway accounts. Request that one account be set up for card-present transactions, and use it solely for that purpose. Use the other for card-not-present transactions. Using the wrong account may result in downgrades.
  • A sale is the preferred method to use for card-present transactions. Consult with your acquiring bank for recommendations on other methods.

Processing Platforms Supporting Card-Present Transactions

The following processing platforms support card-present transactions.

For instructions on setting up or changing your processor, see the Processor Setup Guide PDF.

Note: PayPal Australia (FDRA) merchants with a 12-digit merchant ID, can contact Payflow support to request a 16-digit merchant ID.

  • American Express
  • Elavon
  • First Data Merchant Services (FDMS) Nashville
  • First Data Merchant Services (FDMS) North
  • Global Payments
  • Heartland Payment Systems
  • Litle
  • Merchant e-Solutions
  • Moneris Solutions
  • Paymentech Salem
  • Paymentech Tampa
  • PayPal
  • TeleCheck
  • TSYS Acquiring Solutions
  • Vantiv
  • WorldPay

Card Present Transaction Syntax

Use the SWIPE parameter to pass the Track 1 or Track 2 data (the card's magnetic stripe information). Include either Track 1 or Track 2 data (up to 80 alphanumeric characters). If Track 1 is physically damaged, the POS application can send Track 2 data instead.

The track data includes the disallowed = (equal sign) character. To enable you to use the data, the SWIPE parameter must include a length tag specifying the number of characters in the track data. For this reason, in addition to passing the track data, the POS application counts the characters in the track data and passes that number as the length tag. For details on length tags, see Using Special Characters In Values. The length tag in the following example is [40].

Note: Do not include the ACCT or EXPDATE parameters in card-present transactions. The SWIPE value includes this data.

TRXTYPE=S&TENDER=C&PARTNER=PayPal&USER=SuperMerchant&PWD=SuperMerchant
&SWIPE[40]=;4912000033330026=15121011000012345678?&AMT=21.00

Submit Credit Refund Transactions

The credit transaction (TRXTYPE=C) refunds the specified amount back to the card holder. A credit transaction can contain a reference to the original transaction (referenced) or not (non-referenced) depending on how your account is set up. To issue a credit, the original transaction can only be one of the following: a Sale (TRXTYPE=S), Delayed Capture (TRXTYPE=D) or Voice Authorization (TRXTYPE=F). It is recommended that the merchant issue a credit only if the original transaction has already settled. Even though it is possible to issue a credit to a transaction that has not settled, it is recommended that you void such transactions.

Both the credit transaction and the original transaction will appear on the customer's statement.

Online refunds

Card associations have made changes to how credits are issued as cardholders have become aware of how quickly their online banking account is updated with new purchase information. This is possible as an authorization message passes from the merchant to the cardholder’s financial institution in real-time. Today, purchase return information (credits) can take two to five days to make its way back to the cardholder’s online banking transaction history.

Credits (Refunds) are now processed real-time so that cardholders will be able to quickly view similar updates about pending purchase returns, as they do today for purchases.

Benefits

  • Improves customer experience and satisfaction.
  • Reduces customer service inquiries related to lack of real-time information about a refund status.
  • Provides real-time issuer account validation.
  • Minimizes related chargebacks.

Important: Due to credits (refunds) being real-time, it is possible that a credit can now be declined (RESULT=12) for the same reasons that an authorization would, for example, a closed account, a card reported lost or stolen, etc.

Note: No API changes are required for online refunds as they are handled automatically by Payflow for the processors that support them.

Required Credit Transaction Parameters

The required parameter data for a credit transaction depends on the Allow Non-referenced Credits security setting for your Payflow account. A non-referenced credit is a credit transaction that does not use the credit card information from an existing transaction. You provide the credit card information. As an example, Sally Smith calls you on the phone to cancel an order from your business. To refund her money, submit a non-referenced credit transaction to credit her credit card.

Guidelines and parameter requirements for credit transactions differ depending on whether non-referenced credits are allowed.

Non-Referenced Credits Not Allowed

When non-referenced credits are not allowed (the setting recommended by PayPal), credit transactions are permitted only against existing sale, delayed capture, and voice authorization transactions. To submit a credit transaction when non-referenced credits are not allowed, pass the following parameter:

Parameter Description
ORIGID (Required by some transaction types) ID of the original transaction referenced, or the value returned in the PNREF parameter in the original transaction; it appears as the Transaction ID in PayPal Manager reports.
Limitations: 12 case-sensitive alphanumeric characters.

Set the value of ORIGID to the PNREF value returned for the original transaction. (PayPal Manager reports display the PNREF as the Transaction ID.) If you do not specify an amount, the amount of the original transaction is credited to the card holder.

Non-Referenced Credits Allowed

When non-referenced credits are allowed, credit transactions are permitted in any amount up to the transaction limit for the credit card account that you specify. To submit a credit transaction when non-referenced credits are allowed, you must pass values for the following parameters:

  • ACCT
  • EXPDATE
  • AMT

Note: The default security setting for Gateway accounts is Allow non-referenced credits = No. Sending the ORIGID is the preferred method for performing credit transactions, as described in Non-Referenced Credits Not Allowed. Using the acct, expdate or amt parameters for such restricted accounts leads to the return of result value 117 failed the security check. To help reduce fraud, PayPal recommends that you do not activate non-referenced credits unless you have a business reason. For information on configuring your security settings, see PayPal Manager online help.

Refund Example

The following is an example credit transaction string (non-referenced credits allowed):

TRXTYPE=C&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
&PWD=x1y2z3&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&VERBOSITY=HIGH

Fields Copied From the Original Transaction Into the Credit Transaction

The following fields are copied from the original transaction into the credit transaction (if they exist in the original transaction). If you provide a new value for any of these parameters when you submit the credit transaction, the new value is used. Exceptions are ACCT, EXPDATE, and SWIPE. These parameters retain their original values.

Note: These fields are not copied for referenced credits: TAXAMT, TAXEXEMPT, DUTYAMT, FREIGHTAMT, and, for American Express only, DESC4.

Note: For processors that use the RECURRING parameter, this setting is ignored when forming the credit transaction if you set the RECURRING parameter to Y in the original transaction.

ACCT AMT BILLTOCITY BILLTOCOUNTRY
BILLTOEMAIL BILLTOMIDDLENAME BILLTOLASTNAME BILLTOPHONENUM
BILLTOSTATE BILLTOSTREET BILLTOZIP COMMENT1
COMMENT2 COMPANYNAME CUSTCODE CUSTIP
EXPDATE INVNUM PONUM SHIPTOCITY
SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOMIDDLENAME SHIPTOLASTNAME
SHIPTOSTATE SHIPTOSTREET SHIPTOZIP SWIPE

Submit Inquiry Transactions

An inquiry transaction (TRXTYPE=I) returns the result and status of a transaction.

When To Use an Inquiry Transaction

You can perform an inquiry transaction using a reference to an original transaction — either the PNREF value returned for the original transaction or the CUSTREF value that you specified for the original transaction. You can also perform an inquiry using the secure token.

While the amount of information returned in an inquiry transaction depends upon the VERBOSITY setting, inquiry responses mimic the verbosity level of the original transaction as closely as possible.

Required Parameters for PNREF

To perform an inquiry, pass the following parameter:

|Parameter|Description| | ORIGID | (Required by some transaction types) ID of the original transaction referenced, or the value returned in the PNREF parameter in the original transaction; it appears as the Transaction ID in PayPal Manager reports.
Limitations: 12 case-sensitive alphanumeric characters. |

Set ORIGID to the PNREF (Transaction ID in PayPal Manager reports) value returned in the original transaction.

Inquiry Transaction Parameter String Using the PNREF

This is an example inquiry transaction parameter string using the ORIGID parameter set to the PNREF value:

TRXTYPE=I&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
&PWD=x1y2z3&ORIGID=VPNE12564395&VERBOSITY=HIGH

Required Parameters When Using the CUSTREF

To perform an inquiry transaction when using the CUSTREF, pass the CUSTREF parameter.

|Parameter|Description| | CUSTREF | (Required) Merchant-defined identifier for reporting and auditing purposes. For example, you can set CUSTREF to the invoice number.
You can use CUSTREF when performing inquiry transactions. To make sure that you can always access the correct transaction when you make an inquiry, provide a unique CUSTREF when you submit any transaction, including retries.
Limitations: 12 alphanumeric characters| | | STARTTIME | (Optional) For inquiry transactions when using CUSTREF to specify the transaction. STARTTIME specifies the beginning of the time period during which the transaction specified by the CUSTREF occurred. ENDTIME must be less than 30 days after STARTTIME. You cannot perform an inquiry across a date range greater than 30 days. If you set ENDTIME, and not STARTTIME, STARTTIME defaults to 30 days before ENDTIME.
If you do not specify a STARTTIME or ENDTIME, the system searches the last 30 days.
Limitations: 14 numeric characters in the format yyyymmddhhmmss | | ENDTIME | (Optional) For inquiry transactions when using CUSTREF to specify the transaction. ENDTIME specifies the end of the time period during which the transaction specified by the CUSTREF occurred.
Limitations: 14 numeric characters|

Note: If there are multiple transactions with a particular CUSTREF value, inquiry returns the last transaction only with the specified CUSTREF. To make sure that you can always access the correct transaction, use a unique CUSTREF when you submit any transaction, including retries.

Inquiry Transaction Parameter String Using the CUSTREF

This is an example inquiry parameter string using the CUSTREF.

TRXTYPE=I&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
&PWD=x1y2z3&CUSTREF=Inv00012345

Required Parameters When Using the Secure Token

To perform an inquiry transaction when using the secure token, pass the following parameter:

Parameter Description
SECURETOKEN (Required) A value the Payflow server created upon your request for storing transaction data.
Limitations: 32 alphanumeric characters

Set SECURETOKEN to the PNREF (Transaction ID in PayPal Manager reports) value returned for the original transaction.

Inquiry Parameter String Using the Secure Token

The following is an example inquiry request string with the SECURETOKEN parameter.

TRXTYPE=I&TENDER=C&PARTNER=PayPal&PWD=SuperUserPassword&USER=SuperMerchant&VERBOSITY=HIGH
&VENDOR=SuperMerchant&SECURETOKEN=FmyM1y7wy8kiS6aumnMPhTQN&VERBOSITY=HIGH

The following is the response string.

RESULT=0&PNREF=VFHE1A0CB0A9&TRANSSTATE=6&ORIGRESULT=0&ORIGPNREF=VFHE1A0CB0A8&RESPMSG=Approved
&AUTHCODE=010101&AVSADDR=Y&AVSZIP=Y&HOSTCODE=00&PROCAVS=Y&DATE_TO_SETTLE=2011-02-04 16:16:50
&TRANSTIME=2011-02-04 16:16:50&BILLTOFIRSTNAME=James&BILLTOLASTNAME=Smith&AMT=555.00&ACCT=0002
&EXPDATE=0120&CARDTYPE=0&IAVS=N

Submit Partial Authorizations

A partial authorization is a partial approval of an authorization (TRXTYPE=A) transaction. A partial authorization approves a transaction when the balance available is less than the amount of the transaction. The transaction response returns the amount of the original transaction and the amount approved.

When To Use Partial Authorizations

Use partial authorizations to reduce the number of declines resulting from buyers spending more than their balance on prepaid cards.

Say, for example, that you sell sportswear on your website. Joe purchases a pair of running shoes in the amount of $100.00. At checkout, Joe uses a gift card with a balance of $80.00 to pay. You request partial authorization of $100.00. The transaction response returns the original amount of $100.00 and the approved amount of $80.00.

You can take either of the following actions:

  • Accept the $80.00 and ask the buyer to provide an alternate payment for the additional $20.00.
  • Reject the partial authorization and submit to the card issuer an authorization reversal (Void) for $80.00.

Required Partial Authorization Parameters

To perform a partial authorization, pass the same parameters that you would for an authorization (TRXTYPE=A, ACCT, AMT, and EXPDATE). In addition, pass the following parameters.

Parameter Description
PARTIALAUTH (Required) Set to Y to submit a partial authorization.
Limitations: 1 alphanumeric character.
VERBOSITY (Required) Set to HIGH to obtain information about a partial authorization in the response.

Example Partial Authorization

The following is an example partial authorization.

  • You submit the initial authorization as a partial authorization.

    TRXTYPE=A&TENDER=C&AMT=100.00&ACCT=4111111111111111&EXPDATE=0119 br/`&PARTIALAUTH=Y&VERBOSITY=HIGH`
    
  • The card issuer notes that the card has a remaining balance of $80.00.

  • The card issuer sends a partial authorization for $80.00.

    `RESULT=0&PNREF=VRNS1A3B33C9&RESPMSG=Partial Approval&AUTHCODE=11111&HOSTCODE=E&PROCAVS=U`
    `&TRANSTIME=2010-04-21 11:30:45&AMT=80.00&ORIGAMT=100.00&BALAMT=0&ACCT=1111&EXPDATE=0119&IAVS=X`
    
    • RESPMSG is Partial Approval, AMT is now the actual amount approved, ORIGAMT is the original requested amount, and BALAMT is the balance on the card.
    • Since the amount charged is greater than the amount available on the card, the response sets the balance amount (BALAMT) to zero. If BALAMT is zero, check if there is a balance due by comparing the original amount (ORIGAMT) to the amount charged (AMT).

You can choose to perform one of the following tasks:

  * Accept the $80.00 and request an alternate payment from the buyer for the additional $20.00.
  * Reject the partial authorization by sending the card issuer an authorization reversal (void) for $80.

Submit Purchasing Card Transactions

A purchasing card (also referred to as a commercial card, corporate card, procurement card or business card) is a credit card that an employer requests to be issued. A purchasing card is usually reserved for business-related charges. The card issuer provides specialized reporting for this card type so the employer can monitor the use of the card. There is no method for determining whether a card is a purchase card or a commercial card based on the card number.

To obtain the best bank interchange rates for commercial cards, pass specific additional transaction information. Purchasing card support and parameters vary from processor to processor. See Submit Purchasing Card Level 2 and 3 Transactions.

Note: The PayPal processor does not support purchasing card transactions.

Submit Reference Transactions - Tokenization

To recharge a credit card when you are not storing the credit card information in your local database, you can perform a reference transaction. A reference transaction takes the existing credit card information that is on file and reuses it. (Securely storing data for future reference is also known as tokenization.)

The PNREF returned in the original transaction is valid for use in reference transactions for 12 months and possibly up to 15 months.

For transactions processed by the PayPal processor, use the PPREF returned in the original transaction as the transaction ID, instead of the PNREF.

When To Use a Reference Transaction

Say that Joe Smith purchases a holiday gift from your website store and requests that you send it by UPS ground service. That evening, Joe becomes concerned that the item might not arrive in time for the holiday. So Joe calls you to upgrade shipping to second-day air. You obtain Joe's approval for charging an extra $10 for the upgrade. In this situation, you can create a reference transaction based on the original authorization and charge an additional $10 to Joe's credit card without having to ask him again for credit card information.

Note: As a security measure, reference transactions are disallowed by default. Only your account administrator can enable reference transactions for your account. If you attempt to perform a reference transaction in an account that does not allow reference transactions, Payflow returns RESULT value 117. See PayPal Manager online help for instructions on setting reference transactions and other security features.

Sale and authorization transactions can use a reference transaction as a source of transaction data. Payflow looks up the reference transaction and copies its transaction data into the new sale or authorization. Fraud Protection Service filters do not screen reference transactions.

Note: When the Gateway looks up the reference transaction, it does not alter in any way the transaction referenced or any other transaction in the database. A reference transaction is a read-only operation. Payflow populates with data and acts upon the new transaction only. It does not maintain any linkage between the reference transaction and the new transaction.

You can also initiate reference transactions from PayPal Manager. See PayPal Manager online help for details.

Transaction Types That Can Be Used As the Original Transaction

You can reference the following transaction types to supply data for a new sale or authorization transaction:

  • Authorization (To capture the funds for an approved authorization transaction, be sure to perform a delayed capture transaction, not a reference transaction.)
  • Credit
  • Delayed capture
  • Sale
  • Voice authorization (Payflow does not copy the voice authorization code to the new transaction)
  • Void

Fields Copied From Reference Transactions

The following fields are copied from the reference transaction into the new sale or authorization transaction (if they exist in the original transaction). If you provide a value for any of these parameters when you submit the new transaction, the new value is used.

ACCT BILLTOCITY
EXPDATE BILLTOSTATE
BILLTOFIRSTNAME BILLTOZIP
BILLTOMIDDLENAME BILLTOCOUNTRY
BILLTOLASTNAME SWIPE
BILLTOSTREET

Example Reference Transaction

In this example, you authorize an amount of $100 for a shipment and charge $66 for the first partial shipment using a normal delayed capture. You charge the $34 for the final part of the shipment using a reference transaction to draw credit card and shipping address information from the initial authorization transaction.

This example procedure creates a reference transaction:

Submit the initial transaction, such as an authorization. You use an authorization transaction for the full amount of the purchase of $100 as shown in this transaction request:

TRXTYPE=A&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant
&USER=SuperMerchant&ACCT=5555555555554444&EXPDATE=1215&AMT=100.00
&INVNUM=123456789&BILLTOSTREET=5199 MAPLE&BILLTOZIP=94588

Note the value of the PNREF in the response:

RESULT=0&PNREF=VXYZ01234567&RESPMSG=APPROVED&AUTHCODE=123456&AVSADDR=Y&AVSZIP=N

Note: The PNREF returned in the original transaction is valid in reference transactions for 12 months and possibly up to 15 months.

If the original transaction was processed by the PayPal processor, you can pass either the PNREF of the original transaction in the ORIGID parameter or the PPREF of the original transaction in the ORIGPPREF parameter.

Capture the authorized funds for a partial shipment of $66. When you deliver the first $66 worth of product, you use a normal delayed capture transaction to collect the $66. Set ORIGID to the value of PNREF in the original authorization as in this transaction request.

TRXTYPE=D&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant
&USER=SuperMerchant&ORIGID=VXYZ01234567&AMT=66.00

The following is the response:

RESULT=0&PNREF=VXYZ01234568&AUTHCODE=25TEST&AVSADDR=Y&AVSZIP=N

Note: The TENDER parameter is not required in this step. The TENDER of the capture will be the same as that of the original transaction.

Submit a new sale transaction or an authorization and delayed capture transaction of $34 for the rest of the shipment. When you ship the remainder of the product, you can collect the remaining $34 in a sale transaction that uses the initial authorization as a reference transaction. (This is a sale transaction because Payflow allows only one delayed capture transaction per authorization.)

The following is a sale transaction request:

TRXTYPE=S&TENDER=C&PWD=x1y2z3&PARTNER=PayPal&VENDOR=SuperMerchant
&USER=SuperMerchant&ORIGID=VXYZ01234567&AMT=34.00

The following is the response:

RESULT=0&PNREF=VXYZ01234569&AUTHCODE=25TEST&AVSADDR=Y&AVSZIP=N

Note: If the original transaction was processed by the PayPal processor, pass either the PPREF or PNREF of the original transaction in the ORIGID parameter. Also, if the original transaction was created through Express Checkout or a billing agreement, set the TENDER parameter to TENDER=P.

Data Upload - Storing Credit Card Data on the Gateway Server

To facilitate creating reference transactions while assisting you with PCI compliance, PayPal allows you to upload credit card data by submitting an upload transaction (TRXTYPE=L). At minimum, you must pass values for the following parameters:

  • TRXTYPE
  • TENDER
  • ACCT
  • EXPDATE

This is an example upload transaction request:

TRXTYPE=L&TENDER=C&ACCT=5105105105105100&EXPDATE=1215&BILLTOFIRSTNAME=Ted
&BILLTOLASTNAME=Smith&BILLTOSTREET=123&BILLTOCITY=SanJose&BILLTOSTATE=CA
&BILLTOZIP=12345&BILLTOPHONENUM=123-123-1234

This is the response:

RESULT=0&PNREF=v19A2E710FCF&RESPMSG=Approved&TRANSTIME=2011-11-02 16:53:58

You can send shipping and billing information to be stored, but you must not include the AMT field. If you pass a value for AMT, you will receive an error with RESULT=4 and RESPMSG=Invalid Amount.

Note: PayPal does not verify the credit card data, as it is not sent to the banks for processing. To validate a transaction, you must submit an account verification, also known as a zero dollar authorization (TRXTYPE=A). For details, see Submit Account Verifications.

Submit Sale Transactions

The sale transaction (TRXTYPE=S) charges the specified amount against the account, and marks the transaction for immediate fund transfer during the next settlement period. PayPal submits each merchant's transactions for settlement on a daily basis.

Note: PayPal Payments Advanced and Payflow Link users cannot submit sale transactions unless they use the hosted checkout pages.

When To Use a Sale Transaction

A sale transaction is best suited to businesses that provide immediate fulfillment for their products or services. If your business does not provide immediate fulfillment, credit card association rules recommend that you use an authorization and a delayed capture transaction. For details, see Submit Authorization - Delayed Capture - Transactions. To recharge a credit card when you are not storing the credit card information in your local database, you can perform a new reference transaction based on a Sale transaction.

Note: PayPal Payments Advanced and PayPal Payments Pro merchants who use Fraud Protection Services (FPS) should process their transactions as Authorizations with Delayed Capture instead of a Sale. FPS transactions are treated as authorizations and if the transaction is submitted as a Sale, Payflow auto-captures such transactions approximately every two hours, which may result in a 2-hour or more delay in settling the transaction.

Additional Parameters For Sale Transactions

To perform a sale transaction, pass the following parameters:

  • ACCT
  • AMT
  • EXPDATE

Note: The pin-less debit tender type requires essentially the same parameters as a credit card transaction. In addition to the values required by all transactions, pass values for the ACCT and AMT parameters. The First Data Merchant Services (FDMS) South processing platform supports sale and credit transactions only.

Typical Sale Transaction Parameter String

The following is a typical NVP string passed in a sale transaction.

TRXTYPE=S&TENDER=C&USER=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser&PARTNER=PayPal
&ACCT=5105105105105100&EXPDATE=1215&CVV2=123&AMT=99.00&BILLTOFIRSTNAME=John
&BILLTOLASTNAME=Smith&BILLTOSTREET=123 Main St.&BILLTOCITY=San Jose&BILLTOSTATE=CA
&BILLTOZIP=12345&COMMENT1=Reservation&INVNUM=1234567890&PONUM=C12345&VERBOSITY=HIGH

Besides the required parameters that you pass in a sale transaction, this string includes other typical parameters. The COMMENT1 (and COMMENT2) fields help to track transaction information. Pass the customer's street address (BILLTOSTREET) and zip code (BILLTOZIP) to use address verification service. To validate card security codes, pass the CVV2 parameter. For details on address verification service and card security code, see the following:

Submit Soft Merchant Information

Soft merchant information is detailed data about a merchant such as the merchant's name, business address, business location identifier, and contact information.

About Soft Merchant Information

Merchants aggregators, who perform transactions on behalf of other merchants under a single merchant account, provide the processor with soft merchant information. Soft merchant information identifies the merchant making the sale and includes information about that merchant on the buyer's card statement.

Say, for example, Outdoor Apparel has a chain of 12 stores located in the Western United States with the corporate office in Oakland, California. John Lui purchases a pair of hiking boots online from Hiker's Duds in San Jose, California, and charges them to his credit card. The transaction goes to the aggregator at Outdoor Apparel in Oakland. The aggregator sends soft merchant information about the Hiker's Duds store with the transaction to the credit card processor. When John receives his credit card statement, he recognizes the charge for the hiking boots he purchased at Hiker's Duds in San Jose.

Ways to Send Soft Merchant Information

There are 2 ways you can send soft merchant information:

  • Soft merchant information (SM Record)
  • Merchant descriptor (M Record)

The Paymentech processor requires that you follow their guidelines to send soft descriptor information using either of these methods.

Soft Merchant Information - SM Record

Soft merchant information is for American Express credit cards only. Typically aggregators (and petroleum merchants) pass soft merchant information to the processor in Gateway parameter fields such as the following:

  • MERCHANTNAME
  • MERCHANTSTREET
  • MERCHANTCITY
  • MERCHANTSTATE
  • MERCHANTNAME
  • MERCHANTZIP
  • MERCHANTCOUNTRYCODE
  • MERCHANTLOCATIONID
  • MERCHANTID
  • MERCHANTCONTACTINFO

Note: Paymentech Salem processor only: To take advantage of this level of soft descriptor, you must be approved by the Paymentech Risk/Credit department. Upon approval, Paymentech sets a flag at the transaction division to enable you to send the preceding parameters. If the flag is not set and you send the parameters, your transaction is rejected with Error 258.

Merchant Descriptor - M Record

A merchant descriptor defines the merchant name and product that appears on the account holder's statement. The descriptor information is passed to the processor in parameter fields such as the following:

  • MERCHDESCR - Defines the merchant name and product
  • MERCHSVC - Includes the merchant contact information such as the merchant's telephone number, e-mail address, or website URL

To use merchant descriptors, you are not required to have the processor set the division level flag. However, you are required to obtain prior risk or credit department approval before sending the parameters.

Note: M Record information (merchant soft descriptor information) is also supported for the PayPal processor.

Submit Voice Authorization Transactions

A voice authorization (TRXTYPE=F) is a transaction that the processing network authorizes over the phone.

Note: The PayPal and Moneris processors do not support voice authorization transactions.

When To Use a Voice Authorization Transaction

Some transactions cannot be authorized over the Internet (for example, high dollar amounts) and require manual authorization. These referral transactions generate RESULT value 13.

In these situations, you contact the customer service department of your merchant bank and provide the payment information as requested. If the bank approves the transaction, the bank provides you with a voice authorization code (AUTHCODE) for the transaction.

On approval, a voice authorization transaction is treated like a sale transaction and is settled with no further action on your part.

Like sale transactions, you can void approved voice authorizations before settlement occurs.

Required Voice Authorization Transaction Parameters

To perform a voice authorization transaction, pass the AUTHCODE provided by your merchant bank.

Parameter Description
AUTHCODE (Required for voice authorizations) Returned only for approved voice authorization transactions. AUTHCODE is the approval code received over the phone from the processing network.
Limitations: 6 alphanumeric characters

The following is an example Voice Authorization request parameter string:

TRXTYPE=F&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
&PWD=x1y2z3&AUTHCODE=AB3456&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&VERBOSITY=HIGH

Submit void transactions

The void transaction (TRXTYPE=V) prevents authorizations from being captured, and delayed captures, sales and voice authorizations from being settled.

You cannot void another void transaction or any inquiry type transactions. The void transaction and the original transaction will not appear on the customer's statement.

PayPal will issue an authorization reversal as part of the void transaction for debit and credit cards if the processor supports it. Because the bank or issuer ultimately decides whether to honor authorization reversals, there is no accurate way to determine if an authorization reversal was completed and the hold on funds has been removed.

Note: You can void a PayPal Australia transaction only within one day (24 hours) of the original transaction date and time. If you attempt to void a PayPal Australia transaction older than 24 hours, the API returns error 108.

When To Use a Void Transaction

Use the following guidelines when using void transactions:

  • You can void delayed capture, sale, credit, authorization, and voice authorization transactions. You cannot void a void transaction.
  • You can only use a void transaction on a transaction that has not yet settled. To refund a customer's money for a settled transaction, submit a credit transaction.

Required Void Transaction Parameters

To perform a void transaction, you are required to pass the following parameter:

Parameter Description
ORIGID (Required by some transaction types) ID of the original transaction referenced, or the value returned in the PNREF parameter in the original transaction; it appears as the Transaction ID in PayPal Manager reports.
Limitations: 12 case-sensitive alphanumeric characters

Fields Copied From the Original Transaction Into the Void Transaction

The following fields are copied from the original transaction into the void transaction (if they exist in the original transaction). If you provide a new value for any of these parameters when you submit the void transaction, the new value is used. Exceptions are ACCT, EXPDATE, and SWIPE. These parameters retain their original values.

Note: For processors that use the RECURRING parameter: If you set the RECURRING parameter to Y in the original transaction, the setting is ignored when forming the void transaction.

ACCT AMT BILLTOCITY COMMENT1
COMMENT2 COMPANYNAME BILLTOCOUNTRY CUSTCODE
CUSTIP DUTYAMT BILLTOEMAIL EXPDATE
BILLTOFIRSTNAME BILLTOMIDDLENAME BILLTOLASTNAME FREIGHTAMT
INVNUM PONUM SHIPTOCITY SHIPTOCOUNTRY
SHIPTOFIRSTNAME SHIPTOMIDDLENAME SHIPTOLASTNAME SHIPTOSTATE
SHIPTOSTREET SHIPTOZIP BILLTOSTATE BILLTOSTREET
SWIPE TAXAMT BILLTOPHONENUM TAXEXEMPT
BILLTOZIP

Example Void Transaction Parameter String

The following is an example void transaction string:

TRXTYPE=V&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
&PWD=x1y2z3&ORIGID=VPNE12564395&VERBOSITY=HIGH

Use the Address Verification Service

To qualify for the lowest bank rate, pass address verification service information, including the street address and zip (postal) code.

Address verification service compares the submitted billing street address and zip code with the values on file at the card holder's bank. The response includes values for AVSADDR and AVSZIP: Y, N, or X for the match status of the customer's street address and zip code. Y = match, N = no match, X = card holder's bank does not support address verification service. The address verification service result is for advice only. Banks do not decline transactions based on the address verification service result. The merchant decides to approve or decline a transaction. Most US banks and some international banks support the address verification service.

Note: Address verification service checks only for a street number match, not a street name match, so 123 Main Street returns the same response as 123 Elm Street.

The international address verification service (IAVS) response indicates whether the address verification service response is international (Y), USA (N), or cannot be determined (X).

Note: When you set VERBOSITY to HIGH, the Gateway returns the raw response from the processor in the PROCAVS field. To obtain details about the meaning of the response, contact your merchant bank.

Example Address Verification Service Parameter String

This example request includes the address verification service parameters BILLTOSTREET and BILLTOZIP:

TRXTYPE=A&TENDER=C&PWD=SuperUserPassword&PARTNER=PayPal&VENDOR=Vendor&USER=SuperMerchant
&ACCT=5555555555554444&EXPDATE=1215&AMT=123.00&BILLTOSTREET=5199 Maple&BILLTOZIP=98765

In this example response, the address value matches the value in the bank's records, but the zip code does not. The AVSZIP response is N.

RESULT=0&PNREF=VXW412345678&RESPMSG=APPROVED&AUTHCODE=123456&AVSADDR=Y&AVSZIP=N&IAVS=X

Use the Card Security Code

The card security code is a 3- or 4-digit number (not part of the credit card number) that is printed on the credit card. Because the card security code appears only on the card and not on receipts or statements, the code provides some assurance that the physical card is in the buyer's possession.

This fraud prevention tool has various names, depending on the payment network. Visa calls it CVV2, MasterCard calls it CVC2 while American Express and Discover call it CID. To make sure that your customers see a consistent name, PayPal recommends use of the term card security code on all end-user materials.

On most cards (Diners Club, Discover, Mastercard and Visa) the card security code is a 3-digit number printed on the back of the card (usually in the signature field). All or part of the card number appears before the card security code (567 in the example). American Express prints a 4-digit number (1122 in the example) on the front of the card, above and to the right of the embossed account number. Make sure that you explain this to your customers.

To validate the card security code in a transaction, pass the card security code value in the CVV2 parameter in your request. The response parameter CVV2MATCH returns the result of the card security code check.

Note: To comply with credit card association regulations, do not store the card security code value that you pass in the CVV2 parameter.

Card Security Code

The following example shows a request parameter string.

TRXTYPE=S&TENDER=C&USER=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser&PARTNER=PayPal
&ACCT=5105105105105100&EXPDATE=1215&CVV2=123&AMT=99.00&BILLTOFIRSTNAME=John
&BILLTOLASTNAME=Smith&BILLTOSTREET=123 Main St.&BILLTOCITY=San Jose&BILLTOSTATE=CA&BILLTOZIP=12345

Note: Payflow returns the raw response from the processor in the PROCCVV2 parameter. For details on the meaning of the response, contact your merchant bank.

Information for the PayPal Acquirer

If PayPal is your acquirer, use the following PayPal specific codes.

For all other acquirers, refer to the Country Codes.

Countries and Regions Supported by PayPal

PayPal uses 2-character alpha ISO-3166-1 codes for specifying countries and regions that are supported in fields and variables.

For a complete list of countries and regions supported by PayPal and their 2-character alpha ISO-3166-1 codes, refer to the PayPal API reference list of Countries and Regions.

PayPal Currency Codes

PayPal uses 3-character ISO-4217 codes for specifying currencies in fields and variables. Please refer to the table of currencies supported by PayPal.

American Express MCC Restrictions

Element Description
3000 Series Airlines & Air Carriers (including Charter Airlines)
3000 Series Automobile Rentals
3000 Series Branded Lodging
4011 Railroads (freight)
4111 Local & Suburban Commuter Passenger Transportation
4112 Passenger Railways
4411 Steamships & Cruise Lines (including on-Board Cruise Shop)
4511 Airlines & Air Carriers (including Charter Airlines)
4814 Telecommunications Services
4815 Monthly Summary Telephone Charges
4829 Wire Transfers & Money Order
5172 Petroleum & Petroleum Products
5818 Digital Goods – Large Digital Goods Merchant
5960 Direct Marketing – Insurance Services
5962 Telemarketing – Travel-related Arrangement Services (direct marketing – travel)
5963 Door-to-Door Sales
5966 Direct Marketing – Outbound Telemarketing Merchants
5967 Direct Marketing – Inbound Teleservices Merchant
6010 Financial Institutions – Manual Cash Disbursements
6011 Financial Institutions – Automated Cash Disbursements
6012 Financial Institutions – Merchandise & Services
6051 Non-financial Institutions – foreign currency, money orders (not wire transfer), script, and travelers' checks
6211 Securities – Brokers & Dealers
7012 Timeshares
7322 Debt Collection Agencies
7800 Government-Owned Lotteries
7801 Government-Licensed Casinos (Online Gambling)
7802 Government-Licensed Horse/Dog Racing
7995 Betting & Gambling (including lottery tickets, casino gaming chips, online/ internet gambling, off-track betting and wagers at race tracks)
9402 Postal Services – Government

Last updated November 2016