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 Name | Mandatory? | Description |
|---|---|---|
| checkoutRef | Yes | Unique reference required to continue the transaction on completion of the PayPal Checkout. |
| checkoutName | Yes | Unique name of the required PayPal Checkout. Currently the only supported value is ‘paypal’. |
| checkoutURL | Yes | URL required to load the PayPal Checkout. |
| checkoutRequest | No | Record containing data to send to the PayPal Checkout. |
| checkoutOptions | No | Record containing any checkoutOptions passed in the request or added by the Gateway. |
| acquirerResponseDetails | Yes | Record 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 Name | Mandatory? | Description |
|---|---|---|
| checkoutRef | Yes | Provided if checkoutOnly was used in the continuation response to indicate that a further request will be sent to finalise the transaction. |
| checkoutDetails | Yes | Record 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. |
| acquirerResponseDetails | Yes | Record 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 Name | Mandatory? | Description |
|---|---|---|
| correlationID | No | Correlation ID, which uniquely identifies the transaction to PayPal. |
| checkoutStatus | No | 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 |
| invNum | No | Merchant’s invoice or tracking number, as set sent in checkoutDetails.invNum or assigned by the Gateway. |
| custom | No | Merchant’s invoice or tracking number, as set sent in checkoutDetails.custom or assigned by the Gateway. |
| payPalAdjustment | No | A 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. |
| buyerMarketingEmail | No[2] | Buyer's marketing email address. |
| note | No[3] | Buyer’s note to the Merchant. |
| cartChangeTolerance | No | 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. |
| payerID | No | Buyer’s PayPal Customer Account ID. |
| payerStatus | No | Buyer’s PayPal status. Possible values are: verified unverified |
| billingName | No[4] | Buyer’s name. Also returned in |
| firstName | No[5] | Buyer’s first name. Also returned in |
| middleName | No[2] | Buyer’s middle name. Also returned in |
| lastName | No[2] | Buyer’s last name. Also returned in |
| suffix | No[2] | Buyer’s name suffix. Also returned in |
| business | No | Buyer's business name. Also returned in |
| street | No | Buyer’s street first line. Also returned in |
| street2 | No | Buyer’s street second line. Also returned in |
| city | No | Buyer’s city Also returned in customerTown. |
| state | No | Buyer’s state. Also returned in |
| zip | No | Buyer’s postal code. Also returned in |
| countryCode | No | Buyer's country code. (ISO 2 char. code) Also returned in |
| countryName | No | Buyer's country name. |
| phoneNum | No | Buyer's contact phone number. Also returned in |
| No | Buyer’s email address. Also returned in | |
| shipToName | No | Name of person/entity to ship to. Also returned in |
| shipToStreet | No | Ship to street first line. Also returned in |
| shipToStreet2 | No | Ship to street second line. Also returned in |
| shipToCity | No | Ship to city. Also returned in |
| shipToState | No | Ship to state. Also returned in |
| shipToZip | No | Ship to postal code. Also returned in |
| shipToCountryCode | No | Ship to country code. (ISO 2 char. code) Also returned in |
| shipToCountryName | No | Ship to country name. |
| shipToPhoneNum | No | Ship to phone number. Also returned in |
| shipToAddressStatus | No | Status of shipping address on file with PayPal. Possible values are: none Confirmed Unconfirmed |
| addressNormalizationStatus | No[6] | The PayPal address normalisation status for Brazilian addresses. Possible values are: None Normalized Unnormalized UserPreferred |
| amount | No | Total amount for this order. |
| itemAmount | No | Total item amount for this order. |
| taxAmount | No | Tax amount for this order. |
| exchangeRate | No | Exchange rate for this order. |
| shippingAmount | No | Shipping amount for this order. |
| handlingAmount | No | Handling amount for this order. |
| insuranceAmount | No | Insurance amount for this order. |
| shipDiscountAmount | No | Shipping discount amount for this order. |
| desc | No | Description of items the buyer is purchasing. |
| currencyCode | No | ISO 3-letter currency code. |
| isFinancing | No | 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 |
| financingFeeAmount | No | The 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. |
| financingTerm | No | The length of the financing term, in months. Example values are 6, 12, 18 and 24 months. |
| financingMonthlyPayment | No | This is the estimated amount per month that the Customer will need to pay including fees and interest. |
| financingTotalCost | No | This is the estimated total payment amount including interest and fees that the user will pay during the lifetime of the loan. |
| financingDiscountAmount | No | Discount amount for the buyer if paid in one instalment. |
| regularTakeFeeAmount | No | Fee of the regular take rate on the transaction amount. It could be equal to financingDiscountAmount in the case of non-instalment transactions. |
| noteText | No | Note to Merchant. |
| transactionID | No | PayPal transaction ID. |
| allowedPaymentMethod | No | The payment method type as specified in the initial request. |
| paymentRequestID | No | A unique identifier of the specific payment request. |
| bucketCategoryType | No | The category of a payment as specified in the initial request. |
| instrumentCategory | No | 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. |
| instrumentID | No | An instrument ID (issued by the external party) corresponding to the funding source used in the payment. |
| shippingCalculationMode | No | Describes how the options that were presented to the buyer were determined. Possible values are: API – Callback API – Flatrate |
| insuranceOptionSelected | No | The option that the buyer chose for insurance. Possible values are: Yes – opted for insurance. No – did not opt for insurance. |
| shippingOptionIsDefault | No | 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. |
| shippingOptionAmount | No | The shipping amount that the buyer chose. |
| shippingOptionName | No | The name of the shipping option, such as Air or Ground. |
| scheduledShippingDate | No | The scheduled shipping date is returned only if scheduled shipping options are passed in the request. |
| scheduledShippingPeriod | No | The scheduled shipping period is returned only if scheduled shipping options are passed in the request. |
| sellerPayPalAcountID | No | Unique identifier for the merchant. For parallel payments, this field contains either the Payer Id or the email address of the merchant. |
| taxIDType | No | 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. |
| taxID | No | 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 |
| billingAgreementID | No | Identification 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. |
| billingAgreementAcceptedStatus | No | 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. |
| paymentStatus | No | 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 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 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 Processed – A payment has been accepted. Voided – An authorisation for this transaction has been voided. |
| refundStatus | No | Status of the refund. Possible value are: none – returned if the refund fails instant – refund was instant delayed – refund was delayed |
| pendingReason | No[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. |
| reasonCode | No | 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. |
| protectionEligibilityType | No | 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) |
| feeAmount | No | PayPal fee amount charged for the transaction. |
| settleAmount | No | Amount deposited in your PayPal account after a currency conversion. |
| storeID | No | Store identifier as entered in the transaction. |
| terminalID | No | Terminal identifier as entered in the transaction. |
[8] This value is received directly from PayPal and so will use the ‘ize’ and not ‘ise’ spelling.