Using Other PayPal API Operations

You can use additional PayPal API operations to implement additional features for your buyers or to provide "back office" support.

Issuing Refunds

You can use the RefundTransaction PayPal API operation to issue refunds.

Use the RefundTransaction API to issue one or more refunds associated with a transaction, such as a transaction created by a capture of a payment. The transaction is identified by a transaction ID that PayPal assigns when the payment is captured.

Note:

You cannot make a refund if the transaction occurred after the refund period has passed; typically, the refund period is 60 days.

You can refund amounts up to the total amount of the original transaction. If you specify a full refund, the entire amount is refunded. If you specify a partial refund, you must specify the amount to refund, the currency, and a description of the refund, which is called a memo.

When you call the RefundTransaction API, PayPal responds with another transaction ID, which is associated with the refund (not the original transaction), and additional information about the refund. This information identifies:

  • The gross amount of the refund, which is returned to the payer
  • The amount of the refund associated with the original transaction fee, which is returned to you
  • The net amount of the refund, which is deducted from your balance

To issue a refund:

  1. In the RefundTransaction request, specify the transaction ID of the transaction whose payment you want to refund.
    TRANSACTIONID=transaction_id
    
  2. Specify the kind of refund, which is either Full or Partial.
    REFUNDTYPE=Full
    

    or

    REFUNDTYPE=Partial
    
  3. For a partial refund, specify the refund amount, including the currency.
    AMT=amount
    CURRENCYCODE=currencyID
    
  4. For a partial refund, specify the memo description.
    NOTE=description
    
  5. Execute the RefundTransaction operation.
  6. Check the acknowledgement status in the RefundTransaction response to ensure that the operation was successful.

Handling Payment Review

You are immediately notified that a payment is under review and you should not ship merchandise or, in the case of electronic media, you should not allow download access while the payment is under review. You are notified of the resolution within 24 hours.

Note:

Payment Review is not applicable to Direct Payment.

You can determine the status of a payment in the following ways:

  • By logging in to https://www.paypal.com/ and viewing the status information in the Transaction History
  • By email sent by PayPal
  • By Instant Payment Notification (IPN) message
  • By Payment Data Transfer (PDT) message
  • By checking the status of a transaction programmatically

Programmatically, the merchant can determine the status of a payment by checking the initial status of a transaction using any of the following the API operations:

  • DoExpressCheckoutPayment
  • DoReferenceTransaction
  • DoAuthorization
  • DoReauthorization

You can check the subsequent status of a transaction programmatically by calling the GetTransactionDetails API operation.

Note:

You must use version 58.0 or higher to obtain the initial status information provided by DoExpressCheckoutPayment, DoReferenceTransaction, DoAuthorization, or DoReauthorization.

To use payment review with the DoExpressCheckoutPayment, DoReferenceTransaction, DoAuthorization, and DoReauthorization PayPal API operations, you must:

  1. Check the payment status in the response to the API operation; specifically, check whether PaymentStatus is set to Pending.
  2. If the PaymentStatus is set to Pending, check whether the PendingReason is set to PaymentReview, because there are other reasons that a transaction may become pending. For example, an unsettled authorization's PaymentStatus is set to Pending; however, its PendingReason is set to authorization, which is not related to payment review.

If PaymentStatus is set to Pending and the PendingReason is set to PaymentReview, you should not ship merchandise or, in the case of electronic media, you should not allow download access.

Because the payment status changes after review, you must periodically check the payment status using the GetTransactionDetails API operation.

The following diagram shows how to use the payment status to detect payments under review by PayPal.



TipImportant:

For best results, call the GetTransactionDetails API operation every six hours. PayPal recommends not calling GetTransactionDetails more frequently than once per hour.