Payflow / PayPal Payments Pro / Website Payments Pro - legacy / Integration Guide / Authorizations

Website Payments Pro Authorization and Capture

DocsLegacy


Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

You can use Direct Payment and Express Checkout to authorize payments to be captured later. These payments are known as authorizations.

  • An authorization places a hold on the funds and is valid for 29 days.
  • After a successful authorization, PayPal recommends that you capture the funds within the three-day honor period.
  • Success of the capture is subject to risk and availability of funds on the authorized funding instrument.
  • Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires. A re-authorization generates a new Authorization ID and restarts the honor period and any subsequent capture should be performed on the new Authorization ID. If you do a re-authorization on the 27th day of the authorization, you get only two days of honor period.
  • You can capture less than the original authorization, full authorization amount, or even more than the authorization amount (up to 115% of the original authorization or $75 USD more, whichever is less).

Note: Express Checkout provides an additional option, called an Order, which you use when a single authorization is insufficient. You can create multiple authorizations and capture them as part of the same order. This would be useful, for example, when an order is split into multiple shipments and you need to capture a payment each time part of the order is shipped.

Integration steps

1.OptionalReview support for authorizations and limitations.
2.RequiredAuthorize and capture a payment.
3.OptionalReauthorize and capture a payment.

Support for authorizations and limitations

The honor period is the three-day period during which authorized funds are held.

The valid period is the 29-day period during which the authorization is valid.

After the honor period expires, you can re-authorize the payment, which restarts the three-day honor period. You can re-authorize a payment multiple times during the 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 explicitly reauthorize the honor period before attempting to capture the payment.

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.

You can explicitly void an authorization, in which case, the uncaptured part of the amount specified in the 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.

Authorize and capture a payment

Use these API operations to authorize and capture a payment:

  • DoDirectPayment (NVP, SOAP)
    Set the payment action field to Authorization.
  • DoCapture (NVP, SOAP)
    Capture all or part of the authorized payment in one single capture transaction or in multiple transactions.

Authorize a credit card

The example calls DoDirectPayment to authorize a credit card payment and DoCapture to capture the payment.

Request

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>

Response

A successful authorization returns 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

Capture the payment

Request

Use the authorization 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>

The total capture amount should not exceed 115% or $75 USD more than the authorization amount. When you call DoCapture for the final payment, you must set the complete type 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.

Response

If the capture is 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 becomes the parent transaction ID for the captured transaction.

Reauthorize and capture a payment

Use these API operations to reauthorize and capture a payment:

  • DoReauthorization (NVP, SOAP)
    To capture a payment after the three-day honor period and before the 29-day authorization period, you can explicitly reauthorize the payment before capturing it.
  • DoVoid (NVP, SOAP)
    Optionally, void the entire authorization or void the remaining amount that has not been captured.

Authorize a card

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.

Request

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>

Response

A successful authorization returns 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

Reauthorize a card

Request

To reauthorize a transaction, specify the transaction ID in the DoReauthorization 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 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>

Response

The response contains the 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

Capture the reauthorized payment

Request

To capture the payment, specify 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>

Response

A successful capture has the Completed payment status.

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

Next

Learn about card verifications.

ReferencePayPal.comPrivacyCookiesSupportLegalContact