Paypal IPN variable residence_country belongs to the merchant or to the customer?

Question

The residence_country sent in the IPN belongs to the merchant or to the customer? In the documentation it appears to be related to the merchant (as it is not included in the "Buyer Information Variables" section but in "Transaction and Notification-Related Variables" section) but testing it in the sandbox environment it is equal to the customers residence country.

Also in my tests I noticed that this variable is always the same as address_country_code (except in those cases when the latter is not sent), so which is the real difference between those two? Also, is this variable always sent?

EDIT: After reading the context of this issue: How to decline a Paypal payment if not from a given residence_country?

I think the main question is answered but I still interested in answers for the other two questions.

Answer 1

Yes, account country code is the country in which a PayPal account is based, e.g. "a US PayPal account." Address country code is exactly what it sounds like: the country code of a particular (e.g. shipping) address. So if you have a US PayPal account purchasing something to ship to France, the address would have a different country code than the account itself.

PayPal also has some addresses on file for accounts that are similar to (and often inherited from) credit card billing addresses. An account must have a "primary" address, for example, and I believe that in at least most circumstances this primary address must be in the country of the PayPal account... so while PayPal doesn't have a "billing address" per se, if you ask for a "primary address" rather than a shipping address you will almost always -- but maybe not in every case -- get one with the same country code as the account itself.

To your second question: every address from PayPal should contain a country code, but you will only get an address country code when you are getting an address back from PayPal. If you get two addresses (e.g. account/primary/billing and shipping) you will get two address country codes.

To decline a payment you have many options. In rough order from best to worst for your customers:

1) set up your payment receiving preferences on your receiving account to block the payments you don't want: https://www.paypal.com/us/webapps/helpcenter/helphub/article/?solutionId=FAQ2406 [this functionality isn't a turing-complete payment-refusal grammar so it may or may not support the exact limits you want. But it has some useful features, including that the user will be stopped on the PayPal page itself, thus letting them know reliably and right away that their PayPal account is not being hit.]

2) use GetExpressCheckout to see what the user information is before you call DoExpressCheckout (or similar mechanisms with other integrations, e.g. https://developer.paypal.com/docs/api/#get-user-information; conditionally decide not to create a PayPal transaction at all (and inform the user why!)

3) use payment action = order and look at the results of the order call (either in the api response or the IPN), then reverse/void the order if you don't want to fulfill it

4) as in #3 above but with payment action = authorize, in which case you are freezing the buyer's funds for the duration of the authorization, without intent to deliver product. Not really cool.

5) as in #3 above but with payment action = sale, in which case you re holding the buyer's funds until you reverse/refund (not void) the transaction, without intent do deliver product. Really not cool.

In cases 3 & 4 above it is NOT cool (as is suggested in the other question you reference) not to bother to void the order or auth. Messy -- this leaves you the ability to bill the customer for some time & may encumber their account, and will likely give you some unhappy customers. Any time you are not going to give a customer the product, give up any order or auth you are holding for that product.