Getting Started with Direct Payment
Use the Direct Payment API to accept direct credit card payments on your website from buyers who do not have a PayPal account. PayPal processes the payment in the background.
Note: To determine if you're eligible to accept American Express cards, see the American Express restricted merchant category codes.
|1.||Optional||Learn about the Direct Payment user experience.|
|2.||Required||Meet the prerequisites.|
|3.||Required||Set up your transaction request.|
|4.||Required||Test your Direct Payment integration.|
|5.||Optional||Learn about the Direct Payment checkout UI recommendations.|
The Direct Payment user experience
When a buyer chooses to pay with a credit or debit card, he or she enters card number and other information on your website. After the buyer confirms an order and clicks Pay, your app invokes the
DoDirectPayment API operation to complete the order in the background. Buyers remain on your site and are unaware that PayPal processes the transactions; PayPal will not even appear on the buyer's credit card statement for the transaction.
The following diagram shows a typical Direct Payment flow:
The following steps correspond to the steps in the diagram:
On your checkout pages, you must collect the following information from a buyer to be used in the
- Transaction amount
- Credit card type, number, expiration date and security code
- Cardholder first and last name and billing address
Note: In some cases, the billing address and CSC value may be optional. You must also identify Debit on your PCI compliant checkout page when you reference a direct card checkout image.
You must also retrieve the IP address of the buyer's browser and include this with the request.
When the buyer clicks Pay, your app invokes the
The PayPal API server executes the request and returns a response. The response includes an
Ackcode, indicating the success or failure of the operation and information about the transaction.
If the operation is successful, redirect the buyer to an order confirmation page. Otherwise, you should show the buyer information related to the error. You should also provide an opportunity to pay using a different payment method.
Log in to the PayPal developer portal to manage your PayPal Sandbox test accounts.
One test business account is automatically created for you. Upgrade this account to a Pro account. See accepting credit cards in test transactions.
Either use a random credit card generator to generate test credit card numbers, or create a personal Sandbox account and add a fictitious credit card number to the account. Use this credit card number as a buyer payment card in your test transactions. For more information, see creating Sandbox accounts.
API credentials and endpoints
API credentials are required for all API calls. API credentials can be a signature or certificate. Your API Credentials consist of the
PWD and either a signature or a certificate. PayPal recommends you use certificate credentials for your live application. You can get started quickly with a signature credential for testing purposes within your local network or environment.
You can use test credentials to build your application. Then when your application is ready to go live, you can modify your code to use your live credentials.
Similarly, use the Sandbox endpoint to test your application. Then, when you're ready to go live, update your application to use the live endpoints. See Website Payments Pro Endpoints.
Set up your transaction request
To get started with Direct Payment, implement and test the simplest
DoDirectPayment API operation, which is a sale. Then you can expand your use of Direct Payment to include authorization and capture. A sale is the most straightforward payment action. Use the sale payment action to immediately fulfill an order for digital goods or in-stock inventory.
To make a direct payment, invoke
DoDirectPayment with the transaction amount and buyer payment information.
The assumes that you have met the prerequisites, can communicate with the PayPal server, and that the payment is a final sale.
To set up your transaction request:
Specify the transaction amount in decimals. For non-US dollar transactions, include the currency code and the amount in the supported decimal format for the currency.
Specify the payment action.
Although the default payment action is a
Sale, it is a best practice to explicitly specify the payment action as
Specify the IP address of the buyer's computer.
Specify information about the credit or debit card.
You must specify the kind of credit or debit card and the account number. For testing purposes, use the credit card account that you added to your personal Sandbox account as described in the prerequisites.
The kind of card, the card issuer, and Payment Receiving Preferences settings in your PayPal profile may require you set additional fields.
Important: PayPal recommends that you validate the number of digits entered for the credit card and card verification code before submitting the payment information to PayPal. This will help reduce transaction declines due to buyer error.
Note: UK merchants must also specify values for 3-D Secure-related fields when using Maestro.
Specify information about the card holder.
You must specify the first and last name and the billing address associated with the card:
FIRSTNAME=... LASTNAME=... STREET=... CITY=... STATE=... ZIP=... COUNTRYCODE=...
Important: PayPal recommends that you send the card holder information with every transaction.
Note: The state and zip (postal) code are not required for all countries.
You are now ready to make a call.
Test your Direct Payment integration
The following example uses the
curl command to execute the
DoDirectPayment request and obtain a response. You can use the strategy shown in these steps for initial testing of your Direct Payment implementation. For more complete testing, you should integrate the API requests into your checkout pages.
DoDirectPaymentAPI operation to complete the transaction.
The following example uses cURL to communicate with PayPal:
curl https://api-3t.sandbox.paypal.com/nvp \ --insecure \ -d VERSION=56.0 \ -d SIGNATURE=api_signature \ -d USER=api_username \ -d PWD=api_password \ -d METHOD=DoDirectPayment \ -d PAYMENTACTION=Sale \ -d IPADDRESS=192.168.0.1 \ -d AMT=8.88 \ -d CREDITCARDTYPE=Visa \ -d ACCT=4683075410516684 \ -d EXPDATE=042011 \ -d CVV2=123 \ -d FIRSTNAME=John \ -d LASTNAME=Smith \ -d STREET=1 Main St. \ -d CITY=San Jose \ -d STATE=CA \ -d ZIP=95131 \ -d COUNTRYCODE=US
Test that the response to the
DoDirectPaymentAPI operation was successful.
Ackfield must contain
SuccessWithWarning. However, other fields in the response can help you decide whether to ultimately accept or refund the payment:
TIMESTAMP=... &ACK=Success &VERSION=56%2e0 &BUILD=1195961 &AMT=8%2e88 &CURRENCYCODE=USD &AVSCODE=X &CVV2MATCH=M &TRANSACTIONID=... &CORRELATIONID=...
The response includes the
Ackcode with a value of
FailureWithWarning. Also includes the transaction amount and currency, the card security code (CVV2) or address verification service (AVS) response codes, if enabled, the PayPal transaction ID, the correlation ID, which is a unique ID for the API call, and error codes and error or warning messages, if any.
Log in to your PayPal test account from the Sandbox. When you first log in, the page lists your most recent transactions. Note that if you don't see the Transactions list on the right side of the page, you should see the My recent activity list which also displays the list of recent transactions. If the test transaction was successful, you should see the results in this list.
Click on the title of the transaction to view the Transaction Details page for the transaction. Note that if you are viewing the My recent activity list, you must click the Details link to open the Transaction Details page. The Transaction Details page displays the transaction status and general information about the transaction.
After you execute the
DoDirectPayment API operation, the payment is complete. You cannot capture a further payment or void any part of the payment when you use this payment action.
For additional Website Payments Pro features, return to the Overview page.
User interface recommendations for Direct Payment
Your checkout pages must collect all the information you need to create the
DoDirectPayment request. The request information can be collected by your site's checkout pages.
To make it easier for buyers to enter needed information and to process requests correctly, follow these guidelines:
Important: You are responsible for processing card industry (PCI) compliance for protecting cardholder data. For example, storing the Card Security Code (CSC) violates PCI compliance. For more information about PCI compliance, see PCI Security Standards Council.
- Provide a drop-down menu for the state or province fields for addresses in countries that use them. For U.S. addresses, the state must be a valid 2-letter abbreviation for the state, military location, or U.S. territory. For Canada, the province must be a valid 2-letter province abbreviation. For the UK, do not use a drop-down menu; however, you may need to provide a value for the state in your
- Ensure buyers can enter the correct number of digits for the Card Security Code (CSC). The value is 3 digits for Visa, MasterCard, and Discover. The value is 4 digits for American Express.
- Show information on the checkout page that shows where to find the CSC code on the card and provide a brief explanation of its purpose.
- Configure timeout settings to allow for the fact that the
DoDirectPaymentAPI operation might take as long as 60 seconds to complete, even though completion in less than 3 seconds is typical. Consider displaying a "processing transaction" message to the buyer and disabling the Pay button until the transaction finishes.
- Use the optional Invoice ID field to prevent duplicate charges. PayPal ensures that an Invoice ID is used only once per account. Duplicate requests with the same Invoice ID result in an error and a failed transaction.
Learn how to authorize and capture a payment.
American Express restricted merchant category codes
American Express restricts transactions for certain Merchant Category Classification (MCC) codes, as shown in the table below. PayPal cannot process any American Express transactions at all for these restricted categories.
|Airlines & Air Carriers (including Charter Airlines)|
|4111||Local & Suburban Commuter Passenger Transportation|
|4511||Airlines & Air Carriers (including Charter Airlines)|
|4784||Tolls & Bridge Fees|
|4829||Wire Transfers & Money Order|
|5172||Petroleum & Petroleum Products|
|5815||Digital Goods: Media, Books, Movies, Music|
|5816||Digital Goods: Games|
|5817||Digital Goods: Applications (Excludes Games)|
|5818||Digital Goods: Large Digital Goods Merchant|
|5966||Direct Marketing: Outbound Telemarketing Merchants (telemarketing – merchandise)|
|5967||Direct Marketing: Inbound Telemarketing (internet – electronic delivery internet – adult entertainment internet – online gambling)|
|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|
|7273||Dating & Escort Services, Strippers (e.g., anything sexually explicit; payment of potentially sexually related services)|
|7321||Consumer Credit Reporting Agencies|
|7322||Debt Collection Agencies|
|7512||Automobile Rentals, including Construction Equipment Rentals|