Getting Started With Direct Payment

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.

Implementing the Simplest Direct Payment Integration

To execute a direct payment transaction, you must invoke the DoDirectPayment API operation with sufficient information to identify the buyer's credit or debit card and the amount of the transaction.

This example assumes that you have set up the mechanism you will use to communicate with the PayPal server and have a PayPal business account with API credentials. It also assumes that the payment action is a final sale.

To set up the simplest direct payment transaction

  1. Specify the amount of the transaction; include the currency if it is not in US dollars.

    Specify the total amount of the transaction if it is known; otherwise, specify the subtotal. Regardless of the specified currency, the format must have decimal point with exactly two digits to the right and an optional thousands separator to the left, which must be a comma; for example, EUR 2.000,00 must be specified as 2000.00 or 2,000.00. The specified amount cannot exceed USD $10,000.00, regardless of the currency used.

    AMT=amount
    CURRENCYCODE=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 one of the following values:

    PAYMENTACTION=Sale
    PAYMENTACTION=Authorization
    
  3. Specify the IP address of the buyer's computer.
    IPADDRESS=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:

    CREDITCARDTYPE=Visa
    ACCT=4683075410516684
    

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

    EXPDATE=042011
    CVV2=123
    

    Note: UK merchants must also specify values for 3D Secure-related fields when using Maestro.

  5. 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=...
    

    Note: The state and zip code is not required for all countries.

Testing Direct Payment Using NVP and cURL

To test direct payment, you must first create a test business account in the Sandbox that is enabled for PayPal Payments Pro. You can then use the account to test credit and debit card payments using the DoDirectPayment API operation.

You can then simulate debit or credit card payments from cards that exist in the Sandbox. This example shows how to simulate a DoDirectPayment API operation using cURL to supply the NVP request values and to call DoDirectPayment.

To test Direct Payment in the Sandbox, you must first ensure that the Sandbox test account is associated with a credit card and enabled for Website Payments Pro.

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 cURL into your checkout pages.

The following steps show how you can test the DoDirectPayment API operation:

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

    The following example uses cURL to communicate with PayPal:

    curl --insecure ^
    https://api-3t.sandbox.paypal.com/nvp ^
    -d "VERSION=56.0^
    &SIGNATURE=api_signature^
    &USER=api_username^
    &PWD=api_password^
    &METHOD=DoDirectPayment^
    &PAYMENTACTION=Sale^
    &IPADDRESS=192.168.0.1^
    &AMT=8.88^
    &CREDITCARDTYPE=Visa^
    &ACCT=4683075410516684^
    &EXPDATE=042011^
    &CVV2=123^
    &FIRSTNAME=John^
    &LASTNAME=Smith^
    &STREET=1 Main St.^
    &CITY=San Jose^
    &STATE=CA^
    &ZIP=95131^
    &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:

    TIMESTAMP=...
    &CORRELATIONID=...
    &ACK=Success
    &VERSION=56%2e0
    &BUILD=1195961
    &AMT=8%2e88
    &CURRENCYCODE=USD
    &AVSCODE=X
    &CVV2MATCH=M
    &TRANSACTIONID=...
    

    Note: Values of status fields are simulated because an actual card transaction does not occur.

  3. Log into your PayPal test account from the Sandbox.

    On the My Account Overview page, you should see the results of your transaction if the transaction was successful:



  4. Click the Details link to see the status of the transaction.



Card Verifications

This feature is used to verify that a cardholder’s account is in good standing without processing a purchase transaction or applying a card authorization. American Express does not support card verifications for American Express credit cards. This feature is limited to Mastercard and Visa at this time. It is available for the majority of currencies. The card issuer will decline invalid cards or those reported as lost or stolen. Also, AVS and CVV results are returned where supported by the card issuer.

Card verifications use the DoDirectPayment (NVP | SOAP) API operation, which has been modified to accept an authorization with a zero amount. Similar to a regular authorization, the PaymentAction field value is set to Authorization, but the transaction amount is set to zero. Even though the PaymentAction=Authorization, no authorization or hold is placed on the card holder’s account, and the transaction does not appear on the card holder’s statement. Successful card verification transactions will return Ack=SuccessWithWarning. The response message also includes the code 10574 with the short message Credit Card Verified, so merchants do not mistake this for a financial transaction. If the card is invalid, the response will contain Ack=Failure and an error message. See example. Currently, only Mastercard and Visa support this feature. If the card issuer does not support card verifications, error code 10525 is returned.

Card verifications are considered completed once the response is sent. The paypal.com transaction History page lists card verification transactions as authorization transactions with a zero amount and with a Completed status. Re-authorizations as well as capture and void attempts on card verification transactions are not permitted and will return error code 10575.

Merchants who offer free trial periods, or plan to bill the first installment of a recurring payment at a later date, can verify the buyer's card prior to extending their services. Thus allowing merchants to verify the card before saving the card information and creating the buyer's recurring payments profile. Other merchants who only need to charge the card holder one time after a successful card verification transaction can process a reference transaction using the DoReferenceTransaction (NVP | SOAP) API operation.

Merchants using the Instant Payment Notification service should receive transaction notifications for card verification transactions. Also, similar to other transaction types, the GetTransactionDetails (NVP | SOAP) and TransactionSearch (NVP | SOAP) API operations can be used to lookup transaction details.

Note The card networks discourage the use of $1 authorizations as a method of verifying card status. The rule is that you should only authorize amounts greater than zero on transactions that you intend to capture.

Per transaction fees will apply for card verification transactions, and there is no percentage or discount rate fee associated with these transactions.
For fee information:

  • Go to the PayPal Merchant Fees page.
  • In the Complete Payment Solutions section, expand View all discounts and fees.
  • Scroll to view the per transaction fee for Uncaptured Authorization.

Card Verification Example

This example verifies the buyer's card using the DoDirectPayment API operation. No further action is required.

Important Never use post actions for live transactions; they are not secure.

In your DoDirectPayment request, set the PaymentAction field to Authorization and set the transaction amount to zero:

<form method=post action=https://www.sandbox.paypal.com/nvp>
<input type=hidden name=USER value=...>
<input type=hidden name=PWD value=...>
<input type=hidden name=SIGNATURE value=...>
<input type=hidden name=VERSION value= 58.0>
<input type=hidden name=PAYMENTACTION value=Authorization>
<input type=hidden name=CREDITCARDTYPE value=Visa>
<input type=hidden name=ACCT value=...>
<input type=hidden name=STARTDATE value=112000>
<input type=hidden name=EXPDATE value=112020>
<input type=hidden name=CVV2 value=123>
<input type=hidden name=AMT value=0.00>
<input type=hidden name=CURRENCYCODE value=USD>
<input type=hidden name=FIRSTNAME value=...>
<input type=hidden name=LASTNAME value=...>
<input type=hidden name=STREET value=...>
<input type=hidden name=STREET2  value=>
<input type=hidden name=CITY value="San Francisco">
<input type=hidden name=STATE value=CA>
<input type=hidden name=Zip value=94121>
<input type=hidden name=COUNTRYCODE value=US>
<input type=hidden name=EMAIL value=... >
<input type=submit name=METHOD value=DoDirectPayment>
</form>

If the card verification was successful and the card is valid, the response contains a SuccessWithWarning value in the Ack response field. The response message also includes the code 10574 with the short message Credit Card Verified, so merchants do not mistake this for a financial transaction. The card verification can be tracked and referenced using the TransactionID field:

TIMESTAMP=2010%2d03%2d08T19%3a35%3a18Z&CORRELATIONID=ab12f37f9566&ACK=SuccessWithWarning&VERSION=109%2e0&BUILD=1218643&L_ERRORCODE0=10574&L_SHORTMESSAGE0=Credit%20Card%20Verified&L_LONGMESSAGE0=This%20card%20authorization%20verification%20is%20not%20a%20payment%20transaction.&AMT=0%2e00&CURRENCYCODE=USD&AVSCODE=X&CVV2MATCH=M&TRANSACTIONID=6RH38738S17889722

The verification transaction is now completed.

If the card is invalid, the response will contain Ack=Failure and an error message.

TIMESTAMP=2013%2d10%2d18T05%3a47%3a13Z&CORRELATIONID=68e0c22ecd4fd&ACK=Failure&VERSION=93%2e0&BUILD=8165610&L_ERRORCODE0=15005&L_SHORTMESSAGE0=Processor%20Decline&L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e&L_SEVERITYCODE0=Error&AMT=0%2e00&CURRENCYCODE=USD&AVSCODE=G&CVV2MATCH=I

Direct Payment Authorization and Captures

Sale Payment Action for Direct Payment

A sale payment action represents a single payment that completes a purchase for a specified amount.

A sale is the default payment action; however, you can also specify the action in your DoDirectPayment requests:

PAYMENTACTION=Sale

A sale is the most straightforward payment action. Choose this payment action if the transaction, including shipping of goods, can be completed immediately. Use this payment action when you intend to fulfill the order immediately, such as would be the case for digital goods or for items you have in stock for immediate shipment

After you execute the DoDirectPayment API operation, the payment is complete and further action is unnecessary. You cannot capture a further payment or void any part of the payment when you use this payment action.

Authorization and Capture for Direct Payment

An authorization payment action represents an agreement to pay and places the buyer's funds on hold for up to three days.

To set up an authorization, specify the following payment action in your DoDirectPayment request:

PAYMENTACTION=Authorization

An authorization enables you to capture multiple payments up to 115% of, or USD $75 more than, the amount you initially specify in the DoDirectPayment request. Choose this payment action if you need to ship the goods before capturing the payment or if there is some reason not to accept the payment immediately.

The honor period, for which funds can be held, is 3 days. The valid period, for which the authorization is valid, is 29 days. You can reauthorize the 3-day honor period at most once within the 29-day valid period.

Captures attempted outside of the honor period result in PayPal contacting the card issuer to reauthorize the payment; however, the reauthorization and, thus, the capture might be declined. If you know that you will capture after the honor period expires, PayPal recommends that you call DoReauthorization to explicitly reauthorize the honor period before attempting to capture the payment.

Consider an example in which the buyer orders three $100 items for a total of $300. You specify Authorization for your payment action in the DoDirectPayment request because the goods might not ship at the same time. For each of these items you call DoCapture to collect the payment.

On the first day, you ship the first item and on the third day you ship the second item. The payments for these items succeed because they occur within the honor period. If you ship the third item on the fifth day, your call to DoCapture might fail if the issuer declined the attempt by PayPal to reauthorize. Because the honor period has expired, you should explicitly call DoReauthorization before calling DoCapture to determine whether the buyer's funds are still available. Likewise, if all three items were to be shipped together after the honor period but before the valid period expires, you should explicitly call DoReauthorization before calling DoCapture.

When you call DoCapture for the final payment, you must set the COMPLETETYPE field to Complete. Prior calls to DoCapture must set this field to NotComplete. When payments are complete, any remaining uncaptured amount of the original authorization is automatically voided and nothing more can be captured.

You can explicitly void an authorization, in which case, the uncaptured part of the amount specified in the DoDirectPayment request becomes void and can no longer be captured. If no part of the payment has been captured, the entire payment becomes void and nothing can be captured. For Visa and MasterCard, a hold caused by the authorization is reversed; a bank hold might remain for 7 to 10 days until reversed by the card issuer.

Note: Authorizations become holds on a buyer's account that typically last 3 days for debit cards and 7 to 10 days for credit cards, depending on the issuer and region. If you decide not to capture an authorization, you should void the transaction, which triggers an authorization reversal.
Table 1. API operations associated with the Authorization payment action in DoDirectPayment

API Operation

Description

DoCapture Capture an authorized payment
DoReauthorization Reauthorize a payment
DoVoid Void an authorization

DoDirectPayment Authorization and Capture Example

This example authorizes a credit card payment using the DoDirectPayment API operation and then uses the DoCapture API operation to capture the payment.

Important: Never use post actions for live transactions; they are not secure.

In your DoDirectPayment request, set the payment action to Authorization:

<form method=post action=https://www.sandbox.paypal.com/nvp>
<input type=hidden name=USER value=...>
<input type=hidden name=PWD value=...>
<input type=hidden name=SIGNATURE value=...>
<input type=hidden name=VERSION value= 58.0>
<input type=hidden name=PAYMENTACTION value=Authorization>
<input type=hidden name=CREDITCARDTYPE value=Visa>
<input type=hidden name=ACCT value=...>
<input type=hidden name=STARTDATE value=112000>
<input type=hidden name=EXPDATE value=112020>
<input type=hidden name=CVV2 value=123>
<input type=hidden name=AMT value=20.00>
<input type=hidden name=CURRENCYCODE value=USD>
<input type=hidden name=FIRSTNAME value=...>
<input type=hidden name=LASTNAME value=...>
<input type=hidden name=STREET value=...>
<input type=hidden name=STREET2  value=>
<input type=hidden name=CITY value="San Francisco">
<input type=hidden name=STATE value=CA>
<input type=hidden name=Zip value=94121>
<input type=hidden name=COUNTRYCODE value=US>
<input type=hidden name=EMAIL value=... >
<input type=submit name=METHOD value=DoDirectPayment>
</form>

If the authorization was successful, the response contains the authorization ID in the transaction ID field:

TIMESTAMP=2010%2d03%2d08T19%3a35%3a18Z&CORRELATIONID=ab12f37f9566&ACK=Success&VERSION=58%2e0&BUILD=1218643&AMT=20%2e00&CURRENCYCODE=USD&AVSCODE=X&CVV2MATCH=M&TRANSACTIONID=6RH38738S17889722

Use this ID in the DoCapture request to specify the authorization that you want to capture:

<form method=post action=https://www.sandbox.paypal.com/nvp>
<input type=hidden name=USER value=...>
<input type=hidden name=PWD value=...>
<input type=hidden name=SIGNATURE value=...>
<input type=hidden name=VERSION value= 58.0>
<input type=hidden name=AUTHORIZATIONID value=6RH38738S17889722>
<input type=hidden name=AMT value=5>
<input type=hidden name=CURRENCYCODE value=USD>
<input type=hidden name=COMPLETETYPE value=Complete>
<input type=hidden name=INVNUM value=>
<input type=hidden name=NOTE value= March 08 2010>
<input type=hidden name=SOFTDESCRIPTOR value=>
<input type=submit name=METHOD value=DoCapture>
</form>

If the capture was successful, the payment status is Completed:

AUTHORIZATIONID=6RH38738S17889722&TIMESTAMP=2010%2d03%2d08T19%3a47%3a39Z&CORRELATIONID=d1e8043ae0a12&ACK=Success&VERSION=58%2e0&BUILD=1218643&TRANSACTIONID=5F62121256435650V&PARENTTRANSACTIONID=6RH38738S17889722&RECEIPTID=0078%2d2642%2d6061%2d5728&TRANSACTIONTYPE=webaccept&PAYMENTTYPE=instant&EXPECTEDECHECKCLEARDATE=1970%2d01%2d01T00%3a00%3a00Z&ORDERTIME=2010%2d03%2d08T19%3a47%3a38Z&AMT=5%2e00&FEEAMT=0%2e45&TAXAMT=0%2e00&CURRENCYCODE=USD&PAYMENTSTATUS=Completed&PENDINGREASON=None&REASONCODE=None&PROTECTIONELIGIBILITY=Ineligible
Note: The DoCapture response returns a new transaction ID as well as the authorization ID. The authorization ID is also the parent transaction ID for the completed transaction.

DoDirectPayment Reauthorization and Capture Example

This example authorizes a credit card payment using the DoDirectPayment API operation and then reauthorizes the payment using the DoReauthorization API operation before capturing it with the DoCapture API operation.

Important: Never use post actions for live transactions; they are not secure.

In your DoDirectPayment request, set the payment action to Authorization:

<form method=post action=https://www.sandbox.paypal.com/nvp>
<input type=hidden name=USER value=...>
<input type=hidden name=PWD value=...>
<input type=hidden name=SIGNATURE value=...>
<input type=hidden name=VERSION value= 58.0>
<input type=hidden name=PAYMENTACTION value=Authorization>
<input type=hidden name=CREDITCARDTYPE value=Visa>
<input type=hidden name=ACCT value=...>
<input type=hidden name=STARTDATE value=112000>
<input type=hidden name=EXPDATE value=112020>
<input type=hidden name=CVV2 value=123>
<input type=hidden name=AMT value=500>
<input type=hidden name=CURRENCYCODE value=USD>
<input type=hidden name=FIRSTNAME value=...>
<input type=hidden name=LASTNAME value=...>
<input type=hidden name=STREET value=...>
<input type=hidden name=STREET2 value=>
<input type=hidden name=CITY value="San Francisco">
<input type=hidden name=STATE value=CA>
<input type=hidden name=Zip value=94121>
<input type=hidden name=COUNTRYCODE value=US>
<input type=hidden name=EMAIL value=... >
<input type=submit name=METHOD value=DoDirectPayment>
</form>

If the authorization was successful, the response contains the authorization ID in the transaction ID field:

TIMESTAMP=2010%2d03%2d05T03%3a55%3a13Z&CORRELATIONID=2f8b1e854983e&ACK=Success&VERSION=62%2e0&BUILD=1218643&AMT=500%2e00&CURRENCYCODE=USD&AVSCODE=X&CVV2MATCH=M&TRANSACTIONID=4HS1916972552122T

Use the transaction ID in the DoReauthorization request to identify the authorization that you want to reauthorize:

<form method=post action=https://www.sandbox.paypal.com/nvp>
<input type=hidden name=USER value=...>
<input type=hidden name=PWD value=...>
<input type=hidden name=SIGNATURE value=...>
<input type=hidden name=VERSION value= 62.0>
<input type=hidden name=AUTHORIZATIONID value=4HS1916972552122T>
<input type=hidden name=AMT value=23>
<input type=hidden name=CURRENCYCODE value=USD>
<input type=submit name=METHOD value=DoReauthorization>
</form>

The response to DoReauthorization contains a new authorization ID:

AUTHORIZATIONID=6HB59926VL998415S&TIMESTAMP=2010%2d03%2d08T20%3a37%3a48Z&CORRELATIONID=797da6e380c0&ACK=Success&VERSION=62%2e0&BUILD=1218643&PAYMENTSTATUS=Pending&PENDINGREASON=authorization&PROTECTIONELIGIBILITY=Ineligible

Use the new authorization ID in the DoCapture request:

<form method=post action=https://www.sandbox.paypal.com/nvp>
<input type=hidden name=USER value=...>
<input type=hidden name=PWD value=...>
<input type=hidden name=SIGNATURE value=...>
<input type=hidden name=VERSION value= 62.0>
<input name=AUTHORIZATIONID value=6HB59926VL998415S>
<input name=AMT value=45>
<input name=CURRENCYCODE value=USD>
<input name=COMPLETETYPE value=Complete>
<input name=INVNUM value=>
<input name=NOTE value=>
<input name=SOFTDESCRIPTOR value=>
<input type=submit name=METHOD value=DoCapture>
</form>

If the capture was successful, the payment status is Completed:

AUTHORIZATIONID=6HB59926VL998415S&TIMESTAMP=2010%2d03%2d08T21%3a06%3a01Z&CORRELATIONID=8955b8704da91&ACK=Success&VERSION=62%2e0&BUILD=1218643&TRANSACTIONID=2BG77878LE143642C&PARENTTRANSACTIONID=4HS1916972552122T&RECEIPTID=1115%2d8794%2d3120%2d6892&TRANSACTIONTYPE=webaccept&PAYMENTTYPE=instant&EXPECTEDECHECKCLEARDATE=1970%2d01%2d01T00%3a00%3a00Z&ORDERTIME=2010%2d03%2d08T21%3a06%3a00Z&AMT=45%2e00&FEEAMT=1%2e61&TAXAMT=0%2e00&CURRENCYCODE=USD&PAYMENTSTATUS=Completed&PENDINGREASON=None&REASONCODE=None&PROTECTIONELIGIBILITY=Ineligible
Note: The DoCapture response returns a new transaction ID as well as the authorization ID associated with the reauthorization. The authorization ID is also the parent transaction ID for the completed transaction.