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.

• Obtain an Internet Merchant Account
• About Credit Card Processing
• Credit Card Features
• Plan Your Gateway Integration
• Core Credit Card Parameters
• Submit Account Verifications
• Submit Authorization - Delayed Capture - Transactions
• Submit Balance Inquiry Transactions
• Submit Card Present SWIPE Transactions
• Submit Credit Refund Transactions
• Submit Inquiry Transactions
• Submit Partial Authorizations
• Submit Purchasing Card Transactions
• Submit Reference Transactions Tokenization
• Submit Sale Transactions
• Submit Soft Merchant Information
• Submit Voice Authorization Transactions
• Submit Void Transactions
• Use the Address Verification Service
• Use the Card Security Code
• Information for the PayPal Acquirer

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 FISERV, 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.

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.

Credit Card Features

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

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.

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.

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

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.

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.

Account verification is supported by all processors.

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:

Example Account Verification String

The following is an example of account verification:

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

This is the response:

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

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.

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.

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.

Required Authorization Transaction Parameters

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

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.

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:

Example Balance Inquiry Transaction String

The following is an example of a balance inquiry transaction:

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

This is the response:

1RESULT=0&PNREF=ERRV0A005933&RESPMSG=Approved&AUTHCODE=467PNI&HOSTCODE=000
2&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).

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.

• American Express
• Elavon
• FISERV Nashville
• FISERV 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].

1TRXTYPE=S&TENDER=C&PARTNER=PayPal&USER=SuperMerchant&PWD=SuperMerchant
2&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.

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:

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

Refund Example

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

1TRXTYPE=C&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
2&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.

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:

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:

1TRXTYPE=I&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
2&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.

Inquiry Transaction Parameter String Using the CUSTREF

This is an example inquiry parameter string using the CUSTREF.

1TRXTYPE=I&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
2&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:

1RESULT=19&RESPMSG=Original transaction ID not found: No transaction
2            record found for secure token used.

Inquiry Parameter String Using the Secure Token

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

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

The following is an example response string.

1RESULT=0&PNREF=VFHE1A0CB0A9&TRANSSTATE=6&ORIGRESULT=0&ORIGPNREF=VFHE1A0CB0A8&RESPMSG=Approved
2&AUTHCODE=010101&AVSADDR=Y&AVSZIP=Y&HOSTCODE=00&PROCAVS=Y&DATE_TO_SETTLE=2011-02-04 16:16:50
3&TRANSTIME=2011-02-04 16:16:50&BILLTOFIRSTNAME=James&BILLTOLASTNAME=Smith&AMT=555.00&ACCT=0002
4&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.

Example Partial Authorization

The following is an example partial authorization.

• You submit the initial authorization as a partial authorization.

  1TRXTYPE=A&TENDER=C&AMT=100.00&ACCT=4111111111111111&
  2EXPDATE=0119&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.

  1RESULT=0&PNREF=VRNS1A3B33C9&RESPMSG=Partial Approval&
  2AUTHCODE=11111&HOSTCODE=E&PROCAVS=U&TRANSTIME=2010-04-21 11:30:45&AMT=80.00&ORIGAMT=100.00&BALAMT=0&ACCT=1111&
  3EXPDATE=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.

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.

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.

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.

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:

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

Note the value of the PNREF in the response:

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

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.

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

The following is the response:

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

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:

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

The following is the response:

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

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:

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

This is the response:

1RESULT=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.

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.

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.

Additional Parameters For Sale Transactions

To perform a sale transaction, pass the following parameters:

• ACCT
• AMT
• EXPDATE

Typical Sale Transaction Parameter String

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

1TRXTYPE=S&TENDER=C&USER=SuperUser&PWD=SuperUserPassword&VENDOR=SuperUser&PARTNER=PayPal
2&ACCT=5105105105105100&EXPDATE=1215&CVV2=123&AMT=99.00&BILLTOFIRSTNAME=John
3&BILLTOLASTNAME=Smith&BILLTOSTREET=123 Main St.&BILLTOCITY=San Jose&BILLTOSTATE=CA
4&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 Card Present SWIPE Transactions
• Use the Card Security Code

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

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.

Submit Voice Authorization Transactions

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

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.

The following is an example Voice Authorization request parameter string:

1TRXTYPE=F&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
2&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.

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:

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.

Example Void Transaction Parameter String

The following is an example void transaction string:

1TRXTYPE=V&TENDER=C&PARTNER=PayPal&VENDOR=SuperMerchant&USER=SuperMerchant
2&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.

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

Example Address Verification Service Parameter String

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

1TRXTYPE=A&TENDER=C&PWD=SuperUserPassword&PARTNER=PayPal&VENDOR=Vendor&USER=SuperMerchant
2&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.

1RESULT=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.

Card Security Code

The following example shows a request parameter string.

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

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

_{Last updated November 2016}