Skip to main content

Response Fields

Initial Response (Direct Integration)​

These fields will be returned, in addition to the PayPal Initial Request Fields and the Basic Response Fields minus any card details.

Field NameMandatory?Description
checkoutRefYesUnique reference required to continue the transaction on completion of the PayPal Checkout.
checkoutNameYes

Unique name of the required PayPal Checkout.

Currently the only supported value is ‘paypal’.

checkoutURLYesURL required to load the PayPal Checkout.
checkoutRequestNoRecord containing data to send to the PayPal Checkout.
checkoutOptionsNoRecord containing any checkoutOptions passed in the request or added by the Gateway.
acquirerResponseDetailsYesRecord containing details about the PayPal response containing any PayPal error messages and codes. This can be used together with the normal responseCode and responseMessage response fields to determine further the reason for any failure.

Continuation Response (Direct Integration)​

These fields will be returned, in addition to the PayPal Continuation request fields, the PayPal Initial Response fields and the Basic Response Fields minus any card details.

Field NameMandatory?Description
checkoutRefYesProvided if checkoutOnly was used in the continuation response to indicate that a further request will be sent to finalise the transaction.
checkoutDetailsYesRecord containing values made available by the PayPal Checkout. Refer to here.
customer_XXXX_No[1]Customer details if provided by the PayPal Checkout as detailed here.
delivery_XXXX_No[1]Delivery details if provided by the PayPal Checkout as detailed here.
acquirerResponseDetailsYesRecord containing details about the PayPal response containing any error messages and codes. This can be used together with the normal responseCode and responseMessage response fields to determine further the reason for any failure.

Checkout Details (Hosted and Direct Integration)​

The following details may be provided in the checkoutDetails field included in the response. The details will be returned using the record format.

Sub-Field NameMandatory?Description
correlationIDNoCorrelation ID, which uniquely identifies the transaction to PayPal.
checkoutStatusNo

Status of the Checkout session. If payment is completed, the transaction identification number of the resulting transaction is returned.

Possible values are:

PaymentActionNotInitiated

PaymentActionFailed

PaymentActionInProgress

PaymentActionCompleted

invNumNoMerchant’s invoice or tracking number, as set sent in checkoutDetails.invNum or assigned by the Gateway.
customNoMerchant’s invoice or tracking number, as set sent in checkoutDetails.custom or assigned by the Gateway.
payPalAdjustmentNoA discount or gift certificate offered by PayPal to the buyer. This amount is represented by a negative amount. If the buyer has a negative PayPal account balance, PayPal adds the negative balance to the transaction amount, which is represented as a positive value.
buyerMarketingEmailNo[2]Buyer's marketing email address.
noteNo[3]Buyer’s note to the Merchant.
cartChangeToleranceNo

Indicates whether a cart's contents can be modified. If this parameter is not returned, then assume the cart can be modified. This will return NONE if financing was used in Germany.

Possible values are:

NONE – The cart cannot be changed.

FLEXIBLE – The cart can be changed.

payerIDNoBuyer’s PayPal Customer Account ID.
payerStatusNo

Buyer’s PayPal status.

Possible values are:

verified

unverified

billingNameNo[4]

Buyer’s name.

Also returned in customerName.

firstNameNo[5]

Buyer’s first name.

Also returned in customerName.

middleNameNo[2]

Buyer’s middle name.

Also returned in customerName.

lastNameNo[2]

Buyer’s last name.

Also returned in customerName.

suffixNo[2]

Buyer’s name suffix.

Also returned in customerName.

businessNo

Buyer's business name.

Also returned in customerCompany.

streetNo

Buyer’s street first line.

Also returned in customerAddress.

street2No

Buyer’s street second line.

Also returned in customerAddress.

cityNoBuyer’s city
Also returned in customerTown.
stateNo

Buyer’s state.

Also returned in customerCounty.

zipNo

Buyer’s postal code.

Also returned in customerPostcode.

countryCodeNo

Buyer's country code. (ISO 2 char. code)

Also returned in customerCountryCode.

countryNameNoBuyer's country name.
phoneNumNo

Buyer's contact phone number.

Also returned in customerPhone.

emailNo

Buyer’s email address.

Also returned in customerEmail.

shipToNameNo

Name of person/entity to ship to.

Also returned in deliveryName.

shipToStreetNo

Ship to street first line.

Also returned in deliveryAddress.

shipToStreet2No

Ship to street second line.

Also returned in deliveryAddress.

shipToCityNo

Ship to city.

Also returned in deliveryTown.

shipToStateNo

Ship to state.

Also returned in deliveryCounty.

shipToZipNo

Ship to postal code.

Also returned in deliveryPostcode.

shipToCountryCodeNo

Ship to country code. (ISO 2 char. code)

Also returned in deliveryCountryCode.

shipToCountryNameNoShip to country name.
shipToPhoneNumNo

Ship to phone number.

Also returned in deliveryPhone.

shipToAddressStatusNo

Status of shipping address on file with PayPal.

Possible values are:

none

Confirmed

Unconfirmed

addressNormalizationStatusNo[6]

The PayPal address normalisation status for Brazilian addresses.

Possible values are:

None

Normalized

Unnormalized

UserPreferred

amountNoTotal amount for this order.
itemAmountNoTotal item amount for this order.
taxAmountNoTax amount for this order.
exchangeRateNoExchange rate for this order.
shippingAmountNoShipping amount for this order.
handlingAmountNoHandling amount for this order.
insuranceAmountNoInsurance amount for this order.
shipDiscountAmountNoShipping discount amount for this order.
descNoDescription of items the buyer is purchasing.
currencyCodeNoISO 3-letter currency code.
isFinancingNo

Indicates whether the Customer ultimately was approved for and chose to make the payment using the approved instalment credit.

Possible values are:

FALSE – financing not in use

TRUE – financing approved and used

financingFeeAmountNoThe transaction financing fee associated with the payment. This will be set to the instalment fee amount that is the same as the estimated cost of credit or the interest/fees amount the user will have to pay during the lifetime of the loan. This field will only be included in instalment credit orders. In the case of “same as cash” or “no interest” offers, this will be set to 0.
financingTermNoThe length of the financing term, in months. Example values are 6, 12, 18 and 24 months.
financingMonthlyPaymentNoThis is the estimated amount per month that the Customer will need to pay including fees and interest.
financingTotalCostNoThis is the estimated total payment amount including interest and fees that the user will pay during the lifetime of the loan.
financingDiscountAmountNoDiscount amount for the buyer if paid in one instalment.
regularTakeFeeAmountNoFee of the regular take rate on the transaction amount. It could be equal to financingDiscountAmount in the case of non-instalment transactions.
noteTextNoNote to Merchant.
transactionIDNoPayPal transaction ID.
allowedPaymentMethodNoThe payment method type as specified in the initial request.
paymentRequestIDNoA unique identifier of the specific payment request.
bucketCategoryTypeNoThe category of a payment as specified in the initial request.
instrumentCategoryNo

Identifies the category of the promotional payment instrument.

Possible values are:

1 – PayPal Credit® (formerly Bill Me Later®).

2 – A Private Label Credit Card (PLCC) or co-branded payment card.

instrumentIDNoAn instrument ID (issued by the external party) corresponding to the funding source used in the payment.
shippingCalculationModeNo

Describes how the options that were presented to the buyer were determined.

Possible values are:

API – Callback

API – Flatrate

insuranceOptionSelectedNo

The option that the buyer chose for insurance.

Possible values are:

Yes – opted for insurance.

No – did not opt for insurance.

shippingOptionIsDefaultNo

Indicates whether the buyer chose the default shipping option.

Possible values are:

true – chose the default shipping option.

false – did not choose the default shipping option.

shippingOptionAmountNoThe shipping amount that the buyer chose.
shippingOptionNameNoThe name of the shipping option, such as Air or Ground.
scheduledShippingDateNoThe scheduled shipping date is returned only if scheduled shipping options are passed in the request.
scheduledShippingPeriodNoThe scheduled shipping period is returned only if scheduled shipping options are passed in the request.
sellerPayPalAcountIDNoUnique identifier for the merchant. For parallel payments, this field contains either the Payer Id or the email address of the merchant.
taxIDTypeNo

Buyer's tax ID type. This field is required for Brazil and used for Brazil only.

For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for businesses.

taxIDNo

Buyer's tax ID. This field is required for Brazil and used for Brazil only.

For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14 single-byte characters for businesses

billingAgreementIDNoIdentification number of the billing agreement. When the buyer approves the billing agreement, it becomes valid and remains valid until it is cancelled by the buyer.
billingAgreementAcceptedStatusNo

Indicates whether the buyer accepted the billing agreement for a recurring payment. Currently, this field is always returned in the response for agreement based products, such as subscriptions; reference transactions; recurring payments; and regular single payment transactions.

0 – Not accepted.

1 – Accepted.

paymentStatusNo

Status of the payment.

Possible values are:

None – No status.

Canceled-Reversal – A reversal has been cancelled: for example, when you win a dispute and the funds for the reversal have been returned to you.

Completed – The payment has been completed and the funds have been added successfully to your account balance.

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 authorisation period for this payment has been reached.

Failed – The payment has failed. This happens only if the payment was made from your buyer's bank account.

In-Progress – The transaction has not terminated: for example, an authorisation may be awaiting completion.

Partially-Refunded – The payment has been partially refunded.

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 authorisation for this transaction has been voided.

refundStatusNo

Status of the refund.

Possible value are:

none – returned if the refund fails

instant – refund was instant

delayed – refund was delayed

pendingReasonNo[7]

The reason the payment is pending.

Possible values are:

none – No pending reason.

address – The payment is pending because your buyer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to accept or deny each of these payments manually. To change your preference, go to the Preferences section of your Profile.

authorization[8] – The payment is pending because it has been authorised but not settled. You must capture the funds first.

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.

order – The payment is pending because it is part of an order that has been authorised but not settled.

payment-review – The payment is pending while it is being reviewed by PayPal for risk.

regulatory-review – The payment is pending while we make sure it meets regulatory requirements. You will be contacted again in from 24 to 72 hours with the outcome of the review.

unilateral – The payment is pending because it was made to an email address that is not yet registered or confirmed.

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.

reasonCodeNo

The reason for a reversal if the transaction type is reversal.

Possible values are:

none – No reason code.

chargeback – A reversal has occurred on this transaction due to a chargeback by your buyer.

guarantee – A reversal has occurred on this transaction due to your buyer triggering a money-back guarantee.

buyer-complaint – A reversal has occurred on this transaction due to a complaint about the transaction from your buyer.

refund – A reversal has occurred on this transaction because you have given the buyer a refund.

other – A reversal has occurred on this transaction due to a reason not listed above.

protectionEligibilityTypeNo

The kind of seller protection in force for the transaction.

Possible values are:

ItemNotReceivedEligible – Merchant is protected by PayPal's Seller Protection Policy for Item Not Received.

UnauthorizedPaymentEligible[8] – Merchant is protected by PayPal's Seller Protection Policy for Unauthorised Payments.

Ineligible – Merchant is not protected under the Seller Protection Policy.

(Multiple values are separated by commas)

feeAmountNoPayPal fee amount charged for the transaction.
settleAmountNoAmount deposited in your PayPal account after a currency conversion.
storeIDNoStore identifier as entered in the transaction.
terminalIDNoTerminal identifier as entered in the transaction.

[8] This value is received directly from PayPal and so will use the ‘ize’ and not ‘ise’ spelling.

Footnotes

  1. The response will include Customer/billing address and delivery address details if provided by the PayPal Checkout.
  2. Only available if email option was enabled in the initial request using checkoutOptions.buyerEmailOptInEnable option.
  3. Only available if the leaving of notes was enabled in the initial request using checkoutOptions.allowNote option.
  4. Permission is needed from PayPal to support this field.
  5. This field is passed directly to PayPal and cctherefore the field name and value must be spelt ‘ize’ and not ‘ise’.
  6. pendingReason is returned in the response only if paymentStatus is Pending.
  7. This value is received directly from PayPal and so will use the ‘ize’ and not ‘ise’ spelling.