Authorization & Capture API

The Authorization & Capture API consists of individual requests and responses, as shown below.

Table 3.1

Authorization & Capture API Names, Purposes, and Types of Authorization

API	Purpose	Used With Type of Authorization
DoCapture	Settle an order or previously authorized transaction and obtain payment for either the complete amount or any portion of it.	Order and Basic
DoAuthorization	Authorize an order that can be fulfilled over 29 days.	Order only
DoVoid	Void an original authorization or order	Order and Basic
DoReauthorization	Reauthorize a previously authorized transaction	Basic only

Note:

For more information, see the chapter on Authorization and Capture in the Express Checkout Integration Guide or Website Payment Pro Integration Guide.

DoCapture

DoCaptureRequest is your request to completely or partially settle an order, an authorization, or reauthorization.

Note:

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

DoCapture Types

DoCaptureRequest

Request to capture funds from a PayPal member’s account.

Fields

 

Table 3.2

DoCaptureRequest Fields

Field	Description	Required?
AuthorizationID	xs:string The authorization identification number of the payment you want to capture. This is the transaction id returned from DoExpressCheckoutPayment or DoDirectPayment. Character length and limits: 19 single-byte characters maximum.	Yes
Amount	ebl:BasicAmountType Amount to capture. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).	Yes
CompleteType	ebl:CompleteCodeType The value Complete indicates that this the last capture you intend to make. The value NotComplete indicates that you intend to make additional captures. Note: If Complete, any remaining amount of the original authorized transaction is automatically voided and all remaining open authorizations are voided. Character length and limits: 12 single-byte alphanumeric characters	Yes
InvoiceID	xs:string Your invoice number or other identification number that is displayed to the merchant and customer in his transaction history. Note: This value on DoCapture will overwrite a value previously set on DoAuthorization. Note: The value is recorded only if the authorization you are capturing is an order authorization, not a basic authorization. Character length and limits: 127 single-byte alphanumeric characters	No
Note	xs:string An informational note about this settlement that is displayed to the payer in email and in his transaction history. Character length and limits: 255 single-byte characters	No
SoftDescriptor	xs:string The soft descriptor is a per transaction description of the payment that is passed to the consumer’s credit card statement. If a value for the soft descriptor field is provided, the full descriptor displayed on the customer’s statement has the following format: <PP * | PAYPAL *><Merchant descriptor as set in the Payment Receiving Preferences><1 space><soft descriptor> The soft descriptor can contain only the following characters: l Alphanumeric characters l - (dash) l * (asterisk) l . (period) l {space} If you use any other characters (such as “,”), an error code is returned. The soft descriptor does not include the phone number, which can be toggled between the merchant’s customer service number and PayPal’s customer service number. The maximum length of the total soft descriptor is 22 characters. Of this, either 4 or 8 characters are used by the PayPal prefix shown in the data format. Thus, the maximum length of the soft descriptor passed in the API request is: 22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment Receiving Preferences> + 1) For example, assume the following conditions: l The PayPal prefix toggle is set to PAYPAL * in PayPal’s admin tools l The merchant descriptor set in the Payment Receiving Preferences is set to EBAY. l The soft descriptor is passed in as JanesFlowerGifts LLC The resulting descriptor string on the credit card would be: PAYPAL *EBAY JanesFlow	No

DoCaptureResponse

Response to DoCaptureRequest.

Fields

 

Table 3.3

DoCaptureResponse Fields

Field	Description	Possible Values
AuthorizationID	xs:string The authorization identification number you specified in the request. Character length and limits: 19 single-byte characters maximum	See description.
PaymentInfo	ebl:PaymentInfoType Information about the payment.	See Table 3.4.

Table 3.4

Response: PaymentInfoType Fields

Field	Description
TransactionID	xs:string Unique transaction ID of the payment. Character length and limitations: 17 single-byte characters
ParentTransactionID	xs:string Parent or related transaction identification number. This field is populated for the following transaction types: l Reversal. Capture of an authorized transaction. l Reversal. Reauthorization of a transaction. l Capture of an order. The value of ParentTransactionID is the original OrderID. l Authorization of an order. The value of ParentTransactionID is the original OrderID. l Capture of an order authorization. l Void of an order. The value of ParentTransactionID is the original OrderID. Character length and limits: 16 digits in xxxx-xxxx-xxxx-xxxx format
ReceiptID	xs:string Receipt identification number Character length and limits: 16 digits in xxxx-xxxx-xxxx-xxxx format
TransactionType	ns:PaymentTransactionCodeType The type of transaction l cart l express-checkout Character length and limitations: 15 single-byte characters
PaymentType	ebl:PaymentCodeType Indicates whether the payment is instant or delayed. Character length and limitations: Seven single-byte characters Possible values: none, echeck, instant
PaymentDate	xs:dateTime Time/date stamp of payment. For example: 2006-08-15T17:23:15Z.
GrossAmount	ebl:BasicAmountType The final amount charged, including any shipping and taxes from your Merchant Profile.
FeeAmount	ebl:BasicAmountType PayPal fee amount charged for the transaction
SettleAmount	ebl:BasicAmountType Amount deposited in your PayPal account if there is a currency conversion.
TaxAmount	ebl:BasicAmountType Tax charged on the transaction, if any
ExchangeRate	xs:string 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. Character length and limitations: a decimal multiplier
PaymentStatus	ebl:PaymentStatusCodeType Status of the payment. The status of the payment: l None: No status l Canceled-Reversal: This means a reversal has been canceled. For example, you won a dispute with the customer, and the funds for the transaction that was reversed have been returned to you. l Completed: The payment has been completed, and the funds have been added successfully to your account balance. l Denied: You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element. l Expired: the authorization period for this payment has been reached. l Failed: The payment has failed. This happens only if the payment was made from your customer’s bank account. l Pending: The payment is pending. See the PendingReason field for more information. l Refunded: You refunded the payment. l Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the ReasonCode element. l Processed: A payment has been accepted. l Voided: An authorization for this transaction has been voided.
PendingReason	ebl:PendingStatusCodeType Note: PendingReason is returned in the response only if PaymentStatus is Pending. The reason the payment is pending: l none: No pending reason l address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile. l echeck: The payment is pending because it was made by an eCheck that has not yet cleared. l intl: The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview. l multi-currency: You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment. l verify: The payment is pending because you are not yet verified. You must verify your account before you can accept this payment. l other: The payment is pending for a reason other than those listed above. For more information, contact PayPal Customer Service.

DoAuthorization

Note:

DoAuthorizationRequest is for use only with order authorizations, not basic authorizations.

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.

To use DoAuthorization you must have previously created a customer order. You can create an order in several ways:

l	With the DoExpressCheckoutPaymentRequest or DoDirectPaymentRequest PaymentAction element set to Order.

l	With a shopping cart or PayPal Website Payments transaction with the paymentaction HTML variable set to Order.

Diagram of DoAuthorization Types

The following diagram represents the composition of the DoAuthorizationRequestType and DoAuthorizationResponseType elements. Elements required in the request are marked with an asterisk.

Figure 3.2

DoAuthorization Types

DoAuthorizationRequest

Request to authorize all or part of a customer order amount.

Fields

 

Table 3.5

DoAuthorizationRequest Fields

Field	Description	Required?
TransactionID	xs:string The value of the order’s transaction identification number returned by PayPal. Character length and limits: 19 single-byte characters maximum	Yes
Amount	ebl:BasicAmountType Amount to authorize. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).	Yes
TransactionEntity	ebl:TransactionEntityType Type of transaction to authorize. The only allowable value is Order, which means that the transaction represents a customer order that can be fulfilled over 29 days.	No

DoAuthorizationResponse

Response to DoAuthorizationRequest.

Fields

 

Table 3.6

DoAuthorizationResponse Fields

Field	Description
TransactionID	xs:string An authorization identification number.
Amount	ebl:BasicAmountType The amount you specified in the request.

DoVoid

DoVoidRequest voids an order or an authorization.

IMPORTANT:

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.

Note:

DoVoidRequest is for use with both basic and order authorizations.

Diagram of DoVoid Types

The following diagram represents the composition of the DoVoidRequestType and DoVoidResponseType elements. Elements required in the request are marked with an asterisk.

Figure 3.3

DoVoid Types

DoVoidRequest

Request to void a prior authorization.

Fields

 

Table 3.7

DoVoidRequest Fields

Field	Description	Required?
AuthorizationID	xs:string The value of the original authorization identification number returned by a PayPal product. Important: If you are voiding a transaction that has been reauthorized, use the ID from the original authorization, and not the reauthorization. Character length and limits: 19 single-byte characters	Yes
Note	xs:string An informational note about this void that is displayed to the payer in email and in his transaction history. Character length and limits: 255 single-byte characters	No

DoVoidResponse

Response to DoVoidRequest.

Fields

 

Table 3.8

DoVoidResponse Fields

Field	Description
AuthorizationID	xs:string The authorization identification number you specified in the request. Character length and limits: 19 single-byte characters

DoReauthorization

Note:

DoReauthorization is for use only with basic authorizations, not order authorizations.

To use DoReauthorization you must have previously authorized a transaction and that transaction must have passed its settlement period. Calling DoReauthorization on a valid transaction will fail. You can authorize a transaction in several ways:

l	From the Merchant Services tab of your PayPal merchant account.

l	With the DoExpressCheckoutPaymentRequest PaymentAction element set to Authorization.

l	With a shopping cart transaction (such as one that uses PayPal Website Payments) with the paymentaction HTML variable set to Authorization.

You can invoke DoReauthorization as many times as necessary to obtain one successful reauthorization. When DoReauthorization returns success, the settlement period restarts, you can capture funds, but you can no longer reauthorize.

Diagram of DoReauthorization Types

The following diagram represents the composition of the DoReauthorizationRequestType and DoReauthorizationResponseType elements. Elements required in the request are marked with an asterisk.

Figure 3.4

DoReauthorization Types

 

DoReauthorizationRequest

Request to use Authorization & Capture to reauthorize a transaction.

Fields

 

Table 3.9

DoReauthorizationRequest Fields

Field	Description	Required?
AuthorizationID	xs:string The value of a previously authorized transaction identification number returned by PayPal. Character length and limits: 19 single-byte characters maximum	Yes
Amount	eBL:BasicAmountType Amount to reauthorize. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).	Yes

DoReauthorizationResponse

Response to DoReauthorizationRequest.

Fields

 

Table 3.10

DoReauthorizationResponse Fields

Field	Description
AuthorizationID	xs:string A new authorization identification number. Character length and limits:19 single-byte characters