Authorization & Capture Integration Guide For Professional Use Only Currently only available in English. A usage Professional Uniquement Disponible en Anglais uniquement pour l'instant.
PayPal Authorization & Capture Integration Guide © 2006 PayPal Inc. All rights reserved. PayPal and the PayPal logo are registered trademarks of PayPal, Inc. Designated trademarks and brands are the property of their respective owners. PayPal (Europe) Ltd. is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution. PayPal FSA Register Number: 226056. Notice of Non-Liability PayPal, Inc.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Background Information about the PayPal Web Services API . . . . . . . . . . . . . 11 Organization of This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Notational Conventions . . . . . . . . . . . . .
Contents DoCaptureResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 DoAuthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Diagram of DoAuthorization Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 DoAuthorizationRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 DoAuthorizationResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 DoVoid . . . . . . . . . . . . . . . . . .
Contents Voiding Basic Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Chapter 7 Testing PayPal Authorization & Capture . . . . . . . . . . 55 Features Not Supported in the PayPal Sandbox. . . . . . . . . . . . . . . . . . . . . . . 55 Chapter A PayPal Authorization & Capture Statuses . . . . . . . . . . 57 Appendix B PayPal Authorization & Capture API Error Codes, Short Messages, and Long Messages59 Authorization & Capture API Errors . . . . . . . . . . . . . . .
Contents 6 June 2006 Authorization & Capture Integration Guide
List of Tables Table P.1 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Table 1.2 PayPal Products Supporting Authorization & Capture . . . . . . . . . . . 19 Table 3.3 Authorization & Capture API Names, Purposes, and Types of Authorization . 27 Table 3.4 DoCaptureRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . 29 Table 3.5 DoCaptureResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . 30 Table 3.6 Response: PaymentInfoType Elements . .
List of Tables 8 June 2006 Authorization & Capture Integration Guide
List of Figures Figure 1.1 High-Level Diagram of Authorization & Capture . . . . . . . . 17 Figure 2.2 Capturing Funds Via the Web . . . . . . . . . . . . . . . . 22 Figure 2.3 Voiding an Authorization Via the Web Figure 2.4 Reauthorizing Funds Via the Web Figure 3.5 DoCapture Types . . . . . . . . . . . . . . . . . . . . . . 28 Figure 3.6 DoAuthorization Types Figure 3.7 DoVoid Types . . . . . . . . . . . . . . . . . . . . . . . . 35 Figure 3.8 DoReauthorization Types Figure 4.
List of Figures 10 June 2006 Authorization & Capture Integration Guide
Preface This Document This release of the PayPal Authorization & Capture Integration Guide replaces the version released in December, 2005. Intended Audience This document is written for merchants and developers who use PayPal in their delayed order fulfillment processes.
Preface Notational Conventions Chapter 7, “Testing PayPal Authorization & Capture,” provides information on how to test your web-based or API-based implementation of Authorization & Capture. Notational Conventions This document uses typefaces to identify the characteristics of text. These typefaces and the characteristics they imply are described below: Typeface How Used serif italics A document title. A term being discussed or defined.
Preface Documentation Problems Text attribute How Used xxxxxx Hypertext link to a page in the current document or to another document in the set. xxxxxx Hypertext link to a URL or that initiates a web action, such as sending mail. Documentation Problems If you discover any errors in or have any problems with this documentation, please email us by following the instructions below.
Preface Revision History 14 June 2006 Authorization & Capture Integration Guide
1 Overview PayPal Authorization & Capture is a settlement solution that provides merchants increased flexibility in obtaining payments from their buyers. During a traditional sale at PayPal, the authorization and capture action is completed simultaneously. PayPal Authorization & Capture separates the authorization of payment from the capture of the authorized payment. Authorization & Capture is for merchants who have a delayed order fulfillment process and who typically make a $1 auth at checkout.
Overview Honor Period and Authorization Period 2. You cannot reauthorize an order authorization. Honor Period and Authorization Period The honor period and authorization period for orders and basic authorizations differ slightly as described below. However, the following points are true for both types of authorizations: z If you attempt to capture funds outside the honor period, PayPal applies best efforts to capture funds. However, there is a possibility that funds will not be available at that time.
Authorization & Capture Integration Guide June 2006 B Authorization or Order PaymentRequest DoExpressCheckout 1 1 DoAuthorization Response PayPal Web Services API Service response DoAuthorization Request for order auth 2 DoCapture Response DoCapture Request Basic or Order Authorizations: Merchant API Client 3 DoReauthorization Response DoReauthorization Request for basic auth 4 DoVoid Request DoVoid Response Overview Honor Period and Authorization P
Overview Supported PayPal Payment Products 1. Authorization & Capture can be used with different PayPal payment products. For more information, see “Supported PayPal Payment Products.” For example, you can send your buyer through the Website Payments payment flow, passing in the paymentaction variable set to authorization or order, Likewise, you can use the PayPal Express Checkout API with the element set to Authorization or Order.
Overview Supported PayPal Payment Products TABLE 1.2 PayPal Products Supporting Authorization & Capture Product Typical Usage See Also PayPal Express Checkout Authorization or Order Website Payments Pro Integration Guide Direct Payment API N O T E : Direct Payment can create only basic Website Payments Pro Integration Guide authorizations, not order authorizations.
Overview Supported PayPal Payment Products 20 June 2006 Authorization & Capture Integration Guide
2 Basic Authorization & Capture on the PayPal Website Once your buyer has authorized payment, you can complete the following actions: Capture, Void, and Reauthorization. You can complete these actions either via the PayPal website (as described in this chapter) or through the PayPal Web Services API (see Chapter 3, “Authorization & Capture API). To complete these actions through the PayPal website (https://www.paypal.
Basic Authorization & Capture on the PayPal Website Capturing Funds FIGURE 2.2 Capturing Funds Via the Web IMPO RTANT: If you capture an amount different than the amount your buyer originally authorized, PayPal recommends that you explain any unique circumstances in the Note to Buyer field. 3. On the following page, verify that the information is correct and click Capture Funds. An email notification will be sent to your buyer with the capture details.
Basic Authorization & Capture on the PayPal Website Voiding an Authorization Additional Capture You can capture funds and automatically void any remaining amount on the authorization by selecting the No radio button in the Additional Capture Possible field. Choosing this option moves the authorization into a Complete status. Partial Refunds After you capture funds, the funds are classified as a “payment.” You can issue partial refunds on captured funds just as you can for regular PayPal transactions.
Basic Authorization & Capture on the PayPal Website Reauthorizing Payment FIGURE 2.3 Voiding an Authorization Via the Web You can also Void using the PayPal Web Services API. For instructions on how to do this, refer to Chapter 3, “Authorization & Capture API.” Reauthorizing Payment This action initiates a reauthorization for payment. You can initiate a reauthorization if all the following are true: z Reauthorization is attempted from day 4 to 29 of the authorization period.
Basic Authorization & Capture on the PayPal Website Reauthorizing Payment 2. Enter the reauthorization amount on the following screen and click Continue. FIGURE 2.4 Reauthorizing Funds Via the Web 3. Confirm the reauthorization details on the following page and click the Reauthorize button. You can also complete a reauthorization using the PayPal Web Services API. For instructions on how to do this, refer to Chapter 3, “Authorization & Capture API.
Basic Authorization & Capture on the PayPal Website Reauthorizing Payment 26 June 2006 Authorization & Capture Integration Guide
3 Authorization & Capture API The Authorization & Capture API consists of individual requests and responses, as shown below. TABLE 3.3 Authorization & Capture API Names, Purposes, and Types of Authorization Used With Type of Authorization API Purpose 1. DoCapture Settle an order or previously authorized transaction and obtain payment for either the complete amount or any portion of it. Order and Basic 2. DoAuthorization Authorize an order that can be fulfilled over 29 days. Order only 3.
Authorization & Capture API DoCapture DoCapture DoCaptureRequest is your request to completely or partially settle an order, an authorization, or reauthorization. N O T E : DoCaptureRequest is for use with both basic and order authorizations. Diagram of DoCapture Types The following diagram represents the composition of the DoCaptureRequestType and DoCaptureResponseType elements. Elements required in the request are marked with an asterisk. FIGURE 3.
Authorization & Capture API DoCapture DoCaptureRequest Request to capture funds from a PayPal member’s account. Fields TABLE 3.4 DoCaptureRequest Fields Element Description Data Type Allowable Values Required? Authorization ID The authorization identification number of the payment you want to capture. This can be an order number, an order authorization number, or a rauthorization number. Character length and limits: 19 single-byte characters maximum xs:string See description.
Authorization & Capture API DoCapture DoCaptureResponse Response to DoCaptureRequest. Fields TABLE 3.5 DoCaptureResponse Fields Element Description Data Type Possible Values Authorization ID The authorization identification number you specified in the request. Character length and limits: 19 single-byte characters maximum xs:string See description. PaymentInfo Information about the payment. ebl:PaymentInfo See Table 3.6 on page 30. Type TABLE 3.
Authorization & Capture API DoCapture TABLE 3.6 Response: PaymentInfoType Elements Element Description Data Type Possible Values TaxAmount Tax charged on the transaction ebl:BasicAmount Type xs:string Transactionspecific ExchangeRate Exchange rate if a currency conversion occurred. Relevant only if you are billing in the customer’s non-primary currency. If the customer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the customer’s account.
Authorization & Capture API DoCapture TABLE 3.6 Response: PaymentInfoType Elements Element Description Data Type Possible Values PendingReason N O T E : PendingReason is returned in the ebl:PendingStatus CodeType xs:token none address echeck intl multi-currency verify other response only if PaymentStatus is Pending.
Authorization & Capture API DoAuthorization DoAuthorization DoAuthorizationRequest is your request to authorize a customer order that can be fulfilled within 29 days. You use DoAuthorizationRequest when you are ready to ship goods to your customer. After you ship, you can capture funds with DoCapture. N O T E : DoAuthorizationRequest is for use only with order authorizations, not basic authorizations. To use DoAuthorization you must have previously created a customer order.
Authorization & Capture API DoAuthorization DoAuthorizationRequest Request to authorize all or part of a customer order amount. Fields TABLE 3.7 DoAuthorizationRequest Fields Element Description Data Type Allowable Values Required? TransactionID The value of the order’s transaction identification number returned by a PayPal product. Character length and limits: 19 single-byte characters maximum xs:string See description. Yes Amount Amount to authorize.
Authorization & Capture API DoVoid D o Vo i d DoVoidRequest voids an order or an authorization. IMPO RTANT: The AuthorizationID value on DoVoidRequest must be the original authorization identification number, not the value of AuthorizationID returned by DoReauthorizationResponse. By definition, when the authorization period expires, the authorization or reauthorization of a transaction is implicitly voided. N O T E : DoVoidRequest is for use with both basic and order authorizations.
Authorization & Capture API DoVoid DoVoidRequest Request to void a prior authorization. Fields TABLE 3.9 DoVoidRequest Fields Element Description Data Type Allowable Values Required? AuthorizationI D The value of the original authorization identification number returned by a PayPal product. xs:string See description. Yes xs:string See description.
Authorization & Capture API DoReauthorization DoReauthorization To use DoReauthorization you must have previously authorized a transaction. You can authorize a transaction in several ways: – From the Merchant Services tab of your PayPal merchant account. – With the DoExpressCheckoutPaymentRequest PaymentAction element set to Authorization. – With a shopping cart transaction (such as one that uses PayPal Website Payments) with the paymentaction HTML variable set to authorization.
Authorization & Capture API DoReauthorization DoReauthorizationRequest Request to use Authorization & Capture to reauthorize a transaction. Fields TABLE 3.11 DoReauthorizationRequest Fields Element Description Data Type Allowable Values Required? Authorization The value of a previously authorized transaction identification number returned by a PayPal product. xs:string Any previously authorized PayPal transaction identification number. Yes cc:BasicAmount Type See description.
4 Basic Authorization & Capture Scenarios This chapter includes examples of some common scenarios you might encounter when implementing basic authorizations and captures. Capture Within 3 Days 1. Your buyer orders a camera from your website. 2. Your buyer enters payment information and authorizes payment. 3. Send your buyer to PayPal using a hosted flow, specifying the variable paymentaction=authorization 4. PayPal initiates the authorization. 5. On day 3, you ship the camera and capture funds.
Basic Authorization & Capture Scenarios One Authorization, Multiple Captures, and a Refund 2. Your buyer enters payment information and authorizes payment. 3. PayPal initiates the authorization. 4. The DVD player is discontinued. You order a different DVD player from your vendor and notify your buyer of the change. 5. On day 14, the DVD player arrives from your vendor. Because the honor period has passed, you complete a reauthorization for payment.You ship the DVD player and complete the final capture.
Basic Authorization & Capture Scenarios Lower Capture Amount Your Transaction Details shows the following: FIGURE 4.11Transaction Details: Partial Capture, Reauthorization, Refund Lower Capture Amount 1. Your buyer orders a laser printer and a USB cable from your website. Your buyer enters payment information and authorizes payment. 2. Send your buyer to PayPal using a hosted flow, specifying the variable paymentaction=authorization. 3. PayPal initiates the authorization. 4.
Basic Authorization & Capture Scenarios Capture Up to 115% FIGURE 4.12Transaction Details: Partial Capture, Voided Transaction Capture Up to 115% 1. Your buyer places an order from your website. 2. Your buyer enters payment information and authorizes payment. 3. Send your buyer to PayPal using a hosted flow, specifying the variable paymentaction=authorization. 4. PayPal initiates the authorization. 5. You add shipping charges to the order and capture funds on day 1.
Basic Authorization & Capture Scenarios Authorization Expires FIGURE 4.13Transaction Details: Capture up to 115% Authorization Expires 1. Your buyer orders a desktop computer from your website. 2. Your buyer enters payment information and authorizes payment. 3. Send your buyer to PayPal using a hosted flow, specifying the variable paymentaction=authorization. 4. PayPal initiates the authorization. 5. Before you process the transaction, your buyer contacts you to cancel the order. 6.
Basic Authorization & Capture Scenarios Void FIGURE 4.14Transaction Details: Expired Authorization Void 1. Your buyer orders a stereo system from your website. 2. Your buyer enters payment information and authorizes payment. 3. Send your buyer to PayPal using a hosted flow, specifying the variable paymentaction=authorization. 4. PayPal initiates the authorization. 5. Before you process the transaction, your buyer contacts you to cancel the order. 6. You void the transaction.
Basic Authorization & Capture Scenarios Reattempted Capture FIGURE 4.15History: Voided Transaction Reattempted Capture 1. Your buyer orders two sweatshirts from your website. 2. Your buyer enters payment information and authorizes payment. 3. Send your buyer to PayPal using a hosted flow, specifying the variable paymentaction=authorization. 4. PayPal initiates the authorization. 5. On day 3, you attempt to capture funds, but the capture fails.
Basic Authorization & Capture Scenarios Reattempted Capture FIGURE 4.16A Capture Error 6. There was a restriction on the buyer’s account. You contact the buyer to resolve the problem. 7. Your buyer resolves the account problem. 8. You reattempt and successfully capture funds. You ship the order to your buyer. N O T E : The reauthorization scenario is similar to the Reattempted Capture scenario as detailed above.
5 Order Authorizations Scenarios The following are common scenarios you will encounter when implementing order authorizations. Simple Order TABLE 5.13 Simple Order Scenario Action API Call Running Balance Your buyer orders an item from your website. You request an order from PayPal to authorize the payment, specifying the variable paymentaction=order. You receive a response that the order has been created for a payment amount of $100.00.
Order Authorizations Scenarios Concurrent Authorizations Action API Call Running Balance You request an order from PayPal to authorize the payment, specifying the variable paymentaction=order. You receive a response that the order has been created for a payment amount of $100.00. DoExpressCheckoutPaymentRequest with: You request authorization #1 for $75.00. DoAuthorizationRequest <$75.00> Your buyer contacts you and upgrades to next-day shipping. You capture funds in the amount of $80.
Order Authorizations Scenarios Total Capture Hits Relative Tolerance With Open Authorizations Action API Call Running Balance You request authorization #1 on day 1 for $100.00 for the keyboard. You receive a response that the authorization has been created for a payment amount of $100.00. DoAuthorizationRequest <$100.00> You capture authorization #1 for $100.00. You ship the keyboard. DoCaptureRequest $0.00 You request authorization #2 on day 2 for $200.00 for the second component.
Order Authorizations Scenarios Void Authorizations Action API Call Running Balance Your buyer contacts you and adds another item to the order. You request authorization #2 for $60.00, increasing the order total to $1160.00, which exceeds the 115% tolerance limit of the original order. DoAuthorizationRequest <$60.00> You receive a response that the request for authorization #2 has been declined. $0.00 Void Authorizations TABLE 5.
Order Authorizations Scenarios Partial Capture Partial Capture TABLE 5.18 Partial Capture Scenario Action API Call Running Balance Your buyer orders an item from your website. You request an order from PayPal to authorize the payment, specifying the variable paymentaction=order. You receive a response that the order has been created for a payment amount of $100.00. DoExpressCheckoutPaymentRequest with: .You request authorization #1 on day 1 for $100.00.
Order Authorizations Scenarios Complete Capture Action API Call Running Balance You capture authorization #1 for $100.00. You ship the item. DoCaptureRequest $0.00 N O T E : The 52 default for the DoCapture API is a Complete capture, not a Partial capture.
6 Best Practices Capturing Funds on Basic Authorizations PayPal recommends that you capture funds within the honor period of three days because PayPal will honor the funds for a 3-day period after the basic authorization. If you attempt to capture funds after the three-day period and the authorization fails, your request to capture funds may be declined. After day 4 of the authorization period, you can initiate a reauthorization, which will start a new three-day honor period.
Best Practices Voiding Basic Authorizations 54 June 2006 Authorization & Capture Integration Guide
7 Testing PayPal Authorization & Capture You can test your web- or API-based implementation of PayPal Authorization & Capture in the PayPal Sandbox. The PayPal Sandbox supports the paymentaction=order variable in payment flows, the Merchant Services functions, and the Authorization & Capture APIs. To test your implementation of PayPal Authorization & Capture on the PayPal Sandbox, go through the payment flow on https://www.sandbox.paypal.com and pass the variable paymentaction=order.
Testing PayPal Authorization & Capture Features Not Supported in the PayPal Sandbox 56 June 2006 Authorization & Capture Integration Guide
A PayPal Authorization & Capture Statuses An authorization can only have one status at a time. Any status change will overwrite the prior status. Status Description Complete An authorization has a Complete status when the captured amount is at least 100% of the authorization or has been specified “Marked Complete.” Expired The authorization period of 29 days has passed. The authorization had a Pending status when the authorization period was exceeded.
PayPal Authorization & Capture Statuses 58 June 2006 Authorization & Capture Integration Guide
PayPal Authorization & Capture API Error Codes, Short Messages, and Long Messages B Authorization & Capture API Errors TABLE B.
PayPal Authorization & Capture API Error Codes, Short Messages, and Long Messages Authorization & Capture API Errors TABLE B.20 Authorization & Capture API Error Messages 60 Error Code Short Message Long Message Returned By API Call... 10603 The buyer is restricted. The buyer account is restricted. DoAuthorization DoCapture DoReauthorization DoVoid Contact the buyer. 10604 Authorization must include both buyer and seller. Authorization transaction cannot be unilateral.
PayPal Authorization & Capture API Error Codes, Short Messages, and Long Messages TABLE B.20 Authorization & Capture API Error Messages Error Code Short Message Returned By API Call... 10613 Currency mismatch. Currency of capture must be the same as currency of authorization. DoCapture Ensure that the currencies are the same, and retry the request. 10614 Cannot void reauth. You can void only the original authorization, not a reauthorization. DoVoid Void the authorization.
PayPal Authorization & Capture API Error Codes, Short Messages, and Long Messages Authorization & Capture API Errors TABLE B.20 Authorization & Capture API Error Messages 62 Error Code Short Message Returned By API Call... 10623 Maximum number of authorization allowed for the order is reached. Maximum number of authorization allowed for the order is reached. DoAuthorization DoCapture DoReauthorization DoVoid Capture this order.
PayPal Authorization & Capture API Error Codes, Short Messages, and Long Messages TABLE B.20 Authorization & Capture API Error Messages Error Code Short Message 11094 This authorization cannot be voided, reauthorized, or captured against. Returned By API Call... Long Message Correcting This Error... This authorization can only be handled through the marketplace which created it. It cannot directly be voided, reauthorized, or captured against.
PayPal Authorization & Capture API Error Codes, Short Messages, and Long Messages Authorization & Capture API Errors 64 June 2006 Authorization & Capture Integration Guide
C IPN and PayPal Authorization & Capture For details on how to set up and verify IPN, refer to the Order Management Integration Guide. IPN Notifications You will receive IPN notifications when you complete the following transaction activities: z Authorization z Capture z Void The following table contains Authorization & Capture variables returned through IPN. TABLE C.
IPN and PayPal Authorization & Capture TABLE C.21 IPN Variables for PayPal Authorization & Capture Variable Value Description auth_status Pending Open Auth > 0 Completed Funds have been captured and Open Auth = 0 Expired Authorization has expired Voided Authorization has been voided Character Limit Sent With Authorization Sent With Capture Sent With Void x x x N O T E : “Open Auth” refers to an authorization that has remaining funds available to capture or void.
Glossary AVS Address Verification System. A U.S. banking industry standard for confirming the postal address or telephone number associated with a credit card. auth Short for “authorization.” In U.S. banking industry terminology, to electronically check the validity of a credit card number. With Authorization & Capture, an auth is your means to verify that a PayPal member has sufficient funds to meet a payment obligation. capture The request for settlement.
Glossary void In the context of payment processing with Authorization & Capture, to cancel a prior reauthorization of a settlement amount.
