The PayPal API makes powerful functionality available to developers by exposing various features of the PayPal platform. It offers two interfaces:

• Name-Value Pair (NVP) interface
  Communication is achieved by using simple HTML. This is a lightweight approach, but mostly consists of constructing request URLs. More information are available here, but this will not be considered in this post.
  
  
• SOAP interface
  Requests and responses are sent via SOAP. This allows a more object-oriented development and is going to be topic of this post.

Today I'm going to write about how to set up a simple .NET project and to send a request (in this example I retrieve the account balance). In order to get started you might want to have a look at the SOAP API Developer Reference. In order to use the API, you have to get a PayPal developer license. Fortunately this is free and easy to accomplish:

1. Log  into your PayPal account
2. Go to "Profile"
3. Click "API Access"
4. Click "Request API Credentials"
5. Request a signature

You could also create a certificate,  but using the signature is the easiest and most recommend choice. Now you have an username, a password and a signature. Now if you want to mess around with other people's PayPal account, you have to be granted explicit access rights. Since you might have trouble finding somebody willing to do that, you either create one or more sandbox accounts or you own PayPal account.

To grant API permissions you have to do the following:

1. See steps 1-3 above
2. Click "Grant API Permission"
3. Click "Configure a custom API authorization"
4. Enter your username you received earlier
5. Check each API function you want to provide access to (in this case "GetBalance")

This is all that is necessary to have the required access rights. To use the PayPal SOAP API in Visual Studio you first have to add a new web reference to the PayPal schema ( https://www.paypal.com/wsdl/PayPalSvc.wsdl ). To following code demonstrates how to create the service interface.

Dim credentials As New UserIdPasswordType
credentials.Username = "YOUR_USERNAME"
credentials.Password = "YOUR_PASSWORD"
credentials.Signature = "YOUR_SIGNATURE"
credentials.Subject = "PAYPAL_ACCOUNT_EMAIL"

Dim customSecurityHeader As New CustomSecurityHeaderType
customSecurityHeader.Credentials = credentials

Dim ServiceInterface As New PayPalAPISoapBinding
ServiceInterface.Url = "https://api-3t.paypal.com/2.0/"
ServiceInterface.RequesterCredentials = customSecurityHeader

Replace username, password and signature by your own values. The credentials.Subject field is the email your or somebody else's PayPal account to which you have API permissions (see above). This example targets the live production endpoint (https://api-3t.paypal.com/2.0/). If you want to work with the sandbox, please use https://api-3t.sandbox.paypal.com/2.0/. Next we have a look at the request / response handling:

Dim request As New GetBalanceRequestType
request.Version = "59.0" 'required, found in ns:version in PayPalSvc.wsdl

Dim req As New GetBalanceReq
req.GetBalanceRequest = request

Dim response As GetBalanceResponseType
response = ServiceInterface.GetBalance(req)

txtBalance.Text = response.Balance.Value

All request types (such as GetBalanceRequest) are enclosed by a wrapper (here GetBalanceReq). Besides the version attribute (which is required for all requests) GetBalanceRequest does not have any obligatory attributes. The full list of available requests and detailed parameter descriptions can be found in the developer reference mentioned at the beginning of this post.

More examples will be posted in the future. Full source code of the sample ca be found here.