DoReferenceTransaction API Operation (NVP)
APILegacyLast updated: October 12th 2021, @ 6:58:00 pm
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.
Processes a payment from a buyer's account, which is identified by a previous transaction.
DoReferenceTransaction request message
DoReferenceTransaction request fields
Ship to address fields
Field | Description |
---|---|
SHIPTONAME | Person's name associated with this shipping address. It is required if using a shipping address. Character length and limitations: 32 double-byte characters. |
SHIPTOSTREET | First street address. It is required if using a shipping address. Character length and limitations: 100 single-byte characters. |
SHIPTOSTREET2 | (Optional) Second street address. Character length and limitations: 100 single-byte characters. |
SHIPTOCITY | Name of city. It is required if using a shipping address. Character length and limitations: 40 single-byte characters. |
SHIPTOSTATE | State or province. `partial:partials/docs/shared/cl_shiptostate.en-XC` Character length and limitations: 40 single-byte characters. |
SHIPTOZIP | U.S. ZIP code or other country-specific postal code. It is required if using a U.S. shipping address. Character length and limitations: 20 single-byte characters. |
SHIPTOCOUNTRY | Country code. It is required if using a shipping address. Character length and limitations: 2 single-byte characters. |
SHIPTOPHONENUM | (Optional) Phone number. Character length and limitations: 20 single-byte characters. |
Payment details fields
Field | Description |
---|---|
AMT | (Required) The total cost of the transaction to the buyer. If shipping cost and tax charges are known, include them in this value. If not, this value should be the current subtotal of the order. If the transaction includes one or more one-time purchases, this field must be equal to the sum of the purchases. Set this field to Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
CURRENCYCODE | (Optional) A three-character currency code (default is USD). |
ITEMAMT | (Optional) Sum of cost of all items in this order. Note: Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
SHIPPINGAMT | (Optional) Total shipping costs for this order. Note: If you specify a value for Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
INSURANCEAMT | (Optional) Total shipping insurance costs for this order. The value must be non-negative currency amount or Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
SHIPDISCAMT | (Optional) Shipping discount for this order, specified as a negative number. Character length and limitations: `partial:partials/docs/shared/cl_currencylimit_neg.en-XC` |
HANDLINGAMT | (Optional) Total handling costs for this order. Note: If you specify a value for Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
TAXAMT | (Optional) Sum of tax for all items in this order. Note: Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
DESC | (Optional) Description of items the buyer is purchasing. Note: The value you specify is available only if the transaction includes a purchase. This field is ignored if you set up a billing agreement for a recurring payment that is not immediately charged. Character length and limitations: 127 single-byte alphanumeric characters. |
CUSTOM | (Optional) A free-form field for your own use. Note: The value you specify is available only if the transaction includes a purchase. This field is ignored if you set up a billing agreement for a recurring payment that is not immediately charged. Character length and limitations: 256 single-byte alphanumeric characters. |
INVNUM | (Optional) Your own invoice or tracking number.
Note: PayPal recommends using the Important: The value you specify is available only if the transaction includes a purchase. This field is ignored if you set up a billing agreement for a recurring payment that is not immediately charged. Character length and limitations: 256 single-byte alphanumeric characters. |
BUTTONSOURCE | (Optional) An identification code for use by third-party applications to identify transactions. Character length and limitations: 32 single-byte alphanumeric characters. |
NOTIFYURL | (Optional) Your URL for receiving Instant Payment Notification (IPN) about this transaction. If you do not specify this value in the request, the notification URL from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters. |
RECURRING | (Optional) Flag to indicate a recurring transaction. It is one of the following values:
|
BUCKETCATEGORYTYPE | (Optional) The category of a payment. Value is:
|
Payment details item fields
Field | Description |
---|---|
L_ITEMCATEGORYn | Indicates whether the item is digital or physical. For digital goods, this field is required and you must set it to
This field is introduced in version 69.0. |
L_NAMEn | Item name. This field is required when you pass a value for Character length and limitations: 127 single-byte characters. |
L_DESCn | (Optional) Item description. This field is available since version 53.0. Character length and limitations: 127 single-byte characters. |
L_AMTn | Cost of item. This field is required when you pass a value for Note: If you specify a value for Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
L_NUMBERn | (Optional) Item number. These parameters must be ordered sequentially beginning with 0 (for example Character length and limitations: 127 single-byte characters. |
L_QTYn | Item quantity. This field is required when you pass a value for Character length and limitations: Any positive integer. |
L_TAXAMTn | (Optional) Item sales tax. These parameters must be ordered sequentially beginning with 0 (for example Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
PAYMENTINITIATOR |
|
PAYMENTCATEGORY |
|
CARDONFILE |
|
PREVIOUSTRANSACTIONREFERENCE | PayPal transaction ID previously used to charge the buyer. Shows payment processors that you have established a contract with the buyer. |
PREVIOUSNETWORKTRANSACTIONREFERENCE |
|
Ebay item payment details item fields
Field | Description |
---|---|
L_EBAYITEMNUMBERn | (Optional) Auction item number. These parameters must be ordered sequentially beginning with 0 (for example Character length: 765 single-byte characters. |
L_EBAYITEMAUCTIONTXNIDn | (Optional) Auction transaction identification number. These parameters must be ordered sequentially beginning with 0 (for example Character length: 255 single-byte characters. |
L_EBAYITEMORDERIDn | (Optional) Auction order identification number. These parameters must be ordered sequentially beginning with 0 (for example Character length: 64 single-byte characters. |
Reference credit card details fields
Payer information fields
Field | Description |
---|---|
EMAIL | (Optional) Email address of buyer. Character length and limitations: 127 single-byte characters. |
FIRSTNAME | (Conditional) Buyer's first name is required except when the reference transaction is run against a billing agreement. In the case of a billing agreement, the first name field should not be used. Character length and limitations: 64 double-byte characters. |
LASTNAME | (Conditional) Buyer's last name is required except when the reference transaction is run against a billing agreement. In the case of a billing agreement, the last name field should not be used. Character length and limitations: 64 double-byte characters. |
Address fields
Billing address information.
Field | Description |
---|---|
STREET | (Optional) First street address. Character length and limitations: 100 single-byte characters. |
STREET2 | (Optional) Second street address. Character length and limitations: 100 single-byte characters. |
CITY | (Optional) Name of city. Character length and limitations: 40 single-byte characters. |
STATE | (Optional) State or province. Character length and limitations: 40 single-byte characters. |
COUNTRYCODE | (Optional) Country code. Character limit: 2 single-byte characters. |
ZIP | (Optional) U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters. |
DoReferenceTransaction response message
DoReferenceTransaction response fields for Express Checkout
This field is available since version 84.0.
Field | Description |
---|---|
AVSCODE | Returned only for Direct Credit Card transactions. Address Verification System response code. Character limit: One single-byte alphanumeric character. |
CVV2MATCH | Returned only for Direct Credit Card transactions. Result of the CVV2 check by PayPal. |
BILLINGAGREEMENTID | `partial:partials/docs/shared/cl_billingagreementid.en-XC` |
L_FMFfilterIDn | Filter ID, including the filter type (
|
L_FMFfilterNAMEn | Filter name, including the filter type (PENDING , REPORT , or DENY) , the filter NAME, and the entry number, n, starting from 0. |
PAYMENTADVICECODE | A processor response code typically returned on declined Website Payments Pro recurring transactions. Its purpose is to provide merchants with information and specific instructions on how to handle the decline. It is the merchant's responsibility to follow the instructions provided to avoid chargebacks. For details on the meanings of these codes, see AVS, CVV2, and payment advice response codes. Note: If a recurring transaction is declined with a returned |
MSGSUBID | (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. |
Field | Description |
---|---|
TRANSACTIONID | Unique transaction ID of the payment. |
PARENTTRANSACTIONID | Parent or related transaction identification number. This value in this field is for the following transaction types:
|
RECEIPTID | Receipt identification number. Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format. |
TRANSACTIONTYPE | The type of transaction. Value is:
Character length and limitations: 15 single-byte characters. |
PAYMENTTYPE | Indicates whether the payment is instant or delayed. It only applies to Express Checkout reference transactions and is not applicable to direct credit card reference transactions. Value is:
Character length and limitations: Seven single-byte characters. |
ORDERTIME | Date and time stamp of the payment. Character length and limitations: `partial:partials/docs/shared/cl_utcgmtdate_res.en-XC` |
AMT | The final amount charged, including any shipping and taxes from your Merchant Profile. Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
CURRENCYCODE | A 3-character currency code. |
FEEAMT | PayPal fee amount charged for the transaction. Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
SETTLEAMT | Amount deposited in your PayPal account after a currency conversion. Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
TAXAMT | Tax charged on the transaction. Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
EXCHANGERATE | Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency. If the buyer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the buyer's account. Character length and limitations: Decimal value that does not exceed 17 characters, including decimal point. |
PAYMENTSTATUS | Status of the payment. Value is:
|
PENDINGREASON | The reason the payment is pending. Value is:
Note: |
REASONCODE | The reason for a reversal if the transaction type is reversal. Value is:
|
PROTECTIONELIGIBILITY | Prior to version 64.4, the kind of seller protection in force for the transaction. Value is:
|
PROTECTIONELIGIBILITYTYPE | `partial:partials/docs/shared/cl_protectioneligibilitytype.en-XC` |
STOREID |
|
TERMINALID | xs:string . TerminalId as entered in the transaction. |
INSTRUMENTCATEGORY | Returns the category of the instrument only when it is promotional.Value is:
|
INSTRUMENTID | Reserved for future use. Returns an instrument ID (issued by the external party) corresponding to the funding source used in the payment. |
Payment information fields
Field | Description |
---|---|
TRANSACTIONID | Unique transaction ID of the payment. |
PARENTTRANSACTIONID | Parent or related transaction identification number. This value in this field is for the following transaction types:
|
RECEIPTID | Receipt identification number. Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format. |
TRANSACTIONTYPE | The type of transaction. Value is:
Character length and limitations: 15 single-byte characters. |
PAYMENTTYPE | Indicates whether the payment is instant or delayed. It only applies to Express Checkout reference transactions and is not applicable to direct credit card reference transactions. Value is:
Character length and limitations: Seven single-byte characters. |
ORDERTIME | Date and time stamp of the payment. Character length and limitations: `partial:partials/docs/shared/cl_utcgmtdate_res.en-XC` |
AMT | The final amount charged, including any shipping and taxes from your Merchant Profile. Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
CURRENCYCODE | A 3-character currency code. |
FEEAMT | PayPal fee amount charged for the transaction. Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
SETTLEAMT | Amount deposited in your PayPal account after a currency conversion. Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
TAXAMT | Tax charged on the transaction. Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC` |
EXCHANGERATE | Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency. If the buyer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the buyer's account. Character length and limitations: Decimal value that does not exceed 17 characters, including decimal point. |
PAYMENTSTATUS | Status of the payment. Value is:
|
PENDINGREASON | The reason the payment is pending. Value is:
Note: |
REASONCODE | The reason for a reversal if the transaction type is reversal. Value is:
|
PROTECTIONELIGIBILITY | Prior to version 64.4, the kind of seller protection in force for the transaction. Value is:
|
PROTECTIONELIGIBILITYTYPE | `partial:partials/docs/shared/cl_protectioneligibilitytype.en-XC` |
STOREID |
|
TERMINALID | xs:string . TerminalId as entered in the transaction. |
INSTRUMENTCATEGORY | Returns the category of the instrument only when it is promotional.Value is:
|
INSTRUMENTID | Reserved for future use. Returns an instrument ID (issued by the external party) corresponding to the funding source used in the payment. |
Deprecated fields
The following fields are deprecated. Replacement fields are noted when available.