DoCapture API Operation (SOAP)

Captures an authorized payment. (More about authorization and capture)

DoCapture Request Message

DoCapture Request Fields

Field

Description

AuthorizationID

xs:string

(Required) Authorization identification number of the payment you want to capture. This is the transaction ID returned from DoExpressCheckoutPayment, DoDirectPayment, or CheckOut. For point-of-sale transactions, this is the transaction ID returned by the CheckOut call when the payment action is Authorization.

Character length and limitations: 19 single-byte characters maximum

Amount

ebl:BasicAmountType

(Required) Amount to capture.

Note: You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

CompleteType

ebl:CompleteCodeType

(Required) Indicates whether or not this is your last capture. Value is:

  • Complete — This is the last capture you intend to make.

  • NotComplete — 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.

InvoiceID

xs:string

(Optional) Your invoice number or other identification number that is displayed to you and to the buyer in their transaction history. The value is recorded only if the authorization you are capturing is an Express Checkout order authorization.

Note: PayPal recommends using the InvoiceID field to associate transactions with your internal tracking IDs or invoice numbers. Populating the invoice ID field will help you pull transaction information at a later date using only your internal ID.
Important: This value on DoCapture overwrites a value previously set on DoAuthorization.

Character length and limitations: 127 single-byte alphanumeric characters

Note

xs:string

(Optional) An informational note about this settlement that is displayed to the buyer in email and in their transaction history.

Character length and limitations: 255 single-byte characters

SoftDescriptor

xs:string

(Optional) If you provide a value in this field, the full descriptor on the buyer's statement has the following format:

PP*|PAYPAL*<Merchant descriptor in Payment Receiving Preferences>
	<1 space><soft descriptor>

Character length and limitations: The soft descriptor can contain only the following characters:

  • Alphanumeric characters
  • Dash (-)
  • Asterisk (*)
  • Period (.)
  • Space ( )

If you pass any other characters, such as comma (,), PayPal returns an error code.

The soft descriptor can also include a phone number, which can be toggled between the merchant's customer service number and PayPal's Customer Service number.

The maximum length of the soft descriptor is 22 characters. Of this, the PayPal prefix uses either four or eight characters of the data format. Thus, the maximum length of the soft descriptor information that you can pass in this field is:

22 - len(<PP * | PAYPAL *>) - len(Descriptor in Payment Receiving Preferences + 1)

For example, assume the following conditions:

  • The PayPal prefix toggle is set to PAYPAL * in PayPal's administration tools.
  • The merchant descriptor set in the Payment Receiving Preferences is EBAY.
  • The soft descriptor is passed in as JanesFlowerGifts LLC.

The resulting descriptor string on the credit card is:

PAYPAL *EBAY JanesFlow

MerchantStoreDetails

ns:MerchantStoreDetailsType

(Optional) Information about the merchant store.

This field is available since version 82.0.

MsgSubId

xs:string

(Optional) A message ID used for idempotence to uniquely identify a message. This ID can later be used to request the latest results for a previous request without generating a new request. Examples of this include requests due to timeouts or errors during the original request.

Character length and limitations: string of up to 38 single-byte characters.

This field is available since version 92.0.

MerchantStoreDetailsType Fields

Field

Description

StoreID

xs:string

Identifier of the merchant store at which the refund is given. This field is required for point-of-sale transactions.

Character length and limitations: 50 single-byte characters

This field is available since version 82.0.

TerminalID

xs:string

(Optional) ID of the terminal.

Character length and limitations: 50 single-byte characters

This field is available since version 82.0.

DoCapture Response Message

Note: If you use version 56.0 or later of the DoCapture API, only the authorization ID, transaction ID, transaction type, payment date, gross amount, and payment status are guaranteed to be returned. If you need the values of other fields and they are not returned, you can obtain their values later by calling GetTransactionDetails or by using the reporting mechanism. Not applicable to point of sale transactions.

DoCapture Response Fields

Field

Description

AuthorizationID

xs:string

Authorization identification number you specified in the request.

Character length and limits: 19 single-byte characters maximum

PaymentInfo

ebl:PaymentInfoType

Information about the payment.

MsgSubId

xs:string

(Optional) A message ID used for idempotence to uniquely identify a message. This ID can later be used to request the latest results for a previous request without generating a new request. Examples of this include requests due to timeouts or errors during the original request.

Character length and limitations: string of up to 38 single-byte characters.

This field is available since version 92.0.

PaymentInfoType Fields

Field

Description

TransactionID

xs:string

Unique transaction ID of the payment.

Character length and limitations: 17 characters except for transactions of the type Order have a character length of 19.

ParentTransactionID

xs:string

Parent or related transaction identification number. This field is populated for the following transaction types:

  • Reversal. Capture of an authorized transaction.

  • Reversal. Reauthorization of a transaction.

  • Capture of an order. The value of ParentTransactionID is the original OrderID.

  • Authorization of an order. The value of ParentTransactionID is the original OrderID.

  • Capture of an order authorization.

  • Void of an order. The value of ParentTransactionID is the original OrderID.

Character length and limitations: 17 characters except for transactions of the type Order have a character length of 19.

Only authorization of an order and capture of an order authorization apply to point-of-sale transactions.

ReceiptID

xs:string

Receipt identification number.

Character length and limitations: 16 digits

Empty for point-of-sale transactions.

TransactionType

ns:PaymentTransactionCodeType

The type of transaction. Value is:

  • cart

  • express-checkout

Character length and limitations:15 single-byte characters

PaymentType

ebl:PaymentCodeType

Indicates whether the payment is instant or delayed. Value is:

  • none

  • echeck

  • instant

Character length and limitations: 7 single-byte characters

PaymentDate

xs:dateTime

Date/time stamp of the payment.

Character length and limitations:

Date and time are in UTC/GMT format. For example, 2013-08-24T05:38:48Z.

GrossAmount

ebl:BasicAmountType

The final amount charged, including any shipping and taxes from your Merchant Profile. Shipping and taxes do not apply to point-of-sale transactions.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

FeeAmount

ebl:BasicAmountType

PayPal fee amount charged for the transaction.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

SettleAmount

ebl:BasicAmountType

Amount deposited in your PayPal account after a currency conversion.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

TaxAmount

ebl:BasicAmountType

Tax charged on the transaction.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

ExchangeRate

xs:string

Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency. If the customer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the buyer's account.

Character length and limitations: A decimal that does not exceed 17 characters, including decimal point

PaymentStatus

ebl:PendingStatusCodeType

Status of the payment. Value is:

Note: In a successful DoCapture response for a point-of-sale authorization, the only value value is Completed.
  • None — No status

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

  • Completed — The payment has been completed, and the funds have been added successfully to your account balance. This is the only value status for point-of-sale transactions.

  • Denied — You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element.

  • Expired — The authorization period for this payment has been reached.

  • Failed — The payment has failed. This happens only if the payment was made from your customer's bank account.

  • Pending — The payment is pending. See the PendingReason field for more information.

  • Refunded — You refunded the payment.

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

  • Processed — A payment has been accepted.

  • Voided — An authorization for this transaction has been voided.

PendingReason

ebl:PendingStatusCodeType

Note: PendingReason is returned in the response only if PaymentStatus is Pending. This field does not apply to capturing point-of-sale authorizations, which do not create pending payments.

Reason the payment is pending. Value is:

  • none: — No pending reason.

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

  • echeck — The payment is pending because it was made by an eCheck that has not yet cleared.

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

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

  • regulatoryreview - The payment is pending while we make sure it meets regulatory requirements. You will be contacted again in 24-72 hours with the outcome of the review.
  • verify — The payment is pending because you are not yet verified. You must verify your account before you can accept this payment.

  • other — The payment is pending for a reason other than those listed above. For more information, contact PayPal Customer Service.

InstrumentDetails

ns:InstrumentDetailsType

Type of the payment instrument.

ProtectionEligibility

xs:string

Prior to version 64.4, the kind of seller protection in force for the transaction. Value is:

  • Eligible — Merchant is protected by PayPal's Seller Protection Policy for Unauthorized Payment and Item Not Received.

  • PartiallyEligible — Merchant is protected by PayPal's Seller Protection Policy for Item Not Received.

  • Ineligible — Merchant is not protected under the Seller Protection Policy.

ProtectionEligibilityType

xs:string

Since version 64.4, the kind of seller protection in force for the transaction.

It is one or more of the following values:

  • ItemNotReceivedEligible – Merchant is protected by PayPal's Seller Protection Policy for Item Not Received.
  • UnauthorizedPaymentEligible – Merchant is protected by PayPal's Seller Protection Policy for Unauthorized Payment.
  • Ineligible – Merchant is not protected under the Seller Protection Policy.
Note: If more than one of these values is returned in this field, they will be returned in a comma-delimited string; for example, ItemNotReceivedEligible,UnauthorizedPaymentEligible.

This field is available since version 64.4.

InstrumentDetailsType Fields

Field Description

InstrumentCategory

xs:string

This field holds the category of the instrument only when it is promotional. Value is:
1 represents PayPal Credit
2 represents PLCC (Private Label Credit Card) / Co-branded payment cards.

InstrumentID

xs:string

This field holds an instrument ID (issued by the external party) corresponding to the funding source used in the payment.

Additional information