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.

Integration steps

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:

1. On your checkout pages, you must collect the following information from a buyer to be used in the DoDirectPayment request:

   • 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 can be optional. You must also identify Debit on your PCI compliant checkout page when you reference a direct card checkout image.

2. You must also retrieve the IP address of the buyer's browser and include this with the request.

3. When the buyer clicks Pay, your app invokes the DoDirectPayment API operation.

4. The PayPal API server executes the request and returns a response. The response includes an Ack code, indicating the success or failure of the operation and information about the transaction.

5. If the operation succeeds, 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.

Prerequisites

Sandbox accounts

1. Log in to the PayPal developer portal to manage your PayPal sandbox accounts.
2. One test business account is automatically created for you. Upgrade this account to a Pro account. See Create sandbox accounts.
3. Either use the PayPal Developer's 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 USER, PWD and either a signature or a certificate. PayPal recommends you use certificate credentials for your live application. You can get started quickly with signature credentials 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:

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

   1AMT=<amount>
   2CURRENCYCODE=<currencyID>

2. Specify the payment action.

   Although the default payment action is a Sale, it is a best practice to explicitly specify the payment action as PAYMENTACTION=Sale or PAYMENTACTION=Authorization.

3. Specify the IP address of the buyer's computer.

   1IPADDRESS=192.168.0.1

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

   1CREDITCARDTYPE=Visa
   2ACCT=4683075410516684

   The kind of card, the card issuer, and Payment Receiving Preferences settings in your PayPal profile may require you set additional fields.

   1EXPDATE=042011
   2CVV2=123

   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.

5. Specify information about the card holder.

   You must specify the first and last name and the billing address associated with the card:

   1FIRSTNAME=...
   2LASTNAME=...
   3STREET=...
   4CITY=...
   5STATE=...
   6ZIP=...
   7COUNTRYCODE=...

   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.

6. For more information, see DoDirectPayment API Operation (NVP, SOAP).

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.

1. Execute the DoDirectPayment API operation to complete the transaction.

   The following example uses cURL to communicate with PayPal:

   1curl https://api-3t.sandbox.paypal.com/nvp \
   2  --insecure  \
   3  -d VERSION=56.0 \
   4  -d SIGNATURE=<api_signature> \
   5  -d USER=<api_username> \
   6  -d PWD=<api_password> \
   7  -d METHOD=DoDirectPayment \
   8  -d PAYMENTACTION=Sale \
   9  -d IPADDRESS=192.168.0.1 \
   10  -d AMT=8.88 \
   11  -d CREDITCARDTYPE=Visa \
   12  -d ACCT=4683075410516684 \
   13  -d EXPDATE=042011 \
   14  -d CVV2=123 \
   15  -d FIRSTNAME=John \
   16  -d LASTNAME=Smith \
   17  -d STREET=1 Main St. \
   18  -d CITY=San Jose \
   19  -d STATE=CA \
   20  -d ZIP=95131 \
   21  -d COUNTRYCODE=US

2. Test that the response to the DoDirectPayment API operation was successful.

   The Ack field must contain Success or SuccessWithWarning. However, other fields in the response can help you decide whether to ultimately accept or refund the payment:

   1TIMESTAMP=...
   2&ACK=Success
   3&VERSION=56%2e0
   4&BUILD=1195961
   5&AMT=8%2e88
   6&CURRENCYCODE=USD
   7&AVSCODE=X
   8&CVV2MATCH=M
   9&TRANSACTIONID=...
   10&CORRELATIONID=...

   The response includes the Ack code with a value of Success, SuccessWithWarning, Failure or 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.

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

4. 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:

• 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 two-letter abbreviation for the state, military location, or U.S. territory. For Canada, the province must be a valid two-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 DoDirectPayment request.
• Ensure buyers can enter the correct number of digits for the Card Security Code (CSC). The value is three 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 DoDirectPayment API 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.

Next

Learn how to authorize and capture a payment.

Additional information

American Express restricted merchant category codes

American Express restricts transactions for certain Merchant Category Classification (MCC) codes, as shown in the following table. PayPal cannot process any American Express transactions at all for these restricted categories.

_{Last updated November 2016}