# NVP API Web Samples Using PHP

VERSION 5.1.1

This document describes web samples that use PHP to send Name-Value Pair (NVP) API requests to a PayPal server.

This document contains the following sections:

- Required Software
- Installing the Samples
- Running the Samples
- Enabling the Proxy for Samples
- Descriptions of Samples
- API Documentation

## Required Software

The following software is required:

Software | Version | Download Location
--- | --- | ---
PHP with CURL extension enabled | 4.4.2 or greater | http://www.php.net/downloads.php
Apache HTTP Server | 1.3.17 or greater | http://httpd.apache.org/

You must install and configure PHP with the Apache HTTP Server.

## Installing the Samples

Copy the sample folder, `php_nvp_samples`, to the docroot of the Apache HTTP Server. By default docroot is in datadir`/htdocs`.

## Running the Samples

First, make sure that you have installed the required software and the samples.

You can run the samples by entering the following address in a web browser:

    http://name_of_Apache_HTTP_Server:port/php_nvp_samples/index.html

## Enabling the Proxy for Samples

constants.php is the configuration file for Proxy setup.

Update the following variables in constants.php for Proxy configuration.

- USE_PROXY - Set this variable to TRUE to route all the API requests through Proxy(by default it is FALSE).
- PROXY_HOST - Set this variable to Proxy Server name or IP address
- PROXY_PORT - Set this variable to Proxy Server port

## Descriptions of Samples

The web samples consist of the following:

- Charging a Credit Card Using Direct Payment
- Accepting PayPal in Express Checkout
- Capturing the amount of the authorization
- Void the authorization
- Reauthorizing for a different amount
- Getting Transaction Details
- Searching for a Transaction
- Refunding the amount
- Mass Payment
- Common Files

The main page of the samples, index.html, contains links to each sample.

### Charging a Credit Card Using Direct Payment

This sample shows how to use Direct Payment to charge a credit card. Access this sample from the following choices displayed on index.html:

DoDirectPayment - Sale | Charge a credit card. In the `DoDirectPayment` request, the `PAYMENTACTION` parameter is set to `Sale`.
DoDirectPayment - Authorization | Authorize a credit card for later sale. In the `DoDirectPayment` request, the `PAYMENTACTION` parameter is set to `Authorization`.

The primary files for this sample are:

File | Description
--- | ---

`DoDirectPayment.php`

This is the main web page for the DoDirectPayment sample. This page allows the user to enter name, address, amount, and credit card information. It also accept input variable `paymentType` which becomes the value of the `PAYMENTACTION` parameter.

When the user clicks the Submit button, DoDirectPaymentReceipt.php is called.

Called by index.html.

Calls DoDirectPaymentReceipt.php.

`DoDirectPaymentReceipt.php`

Submits a credit card transaction to PayPal using a `DoDirectPayment` request.

The code collects transaction parameters from the form displayed by DoDirectPayment.php then constructs and sends the `DoDirectPayment` request string to the PayPal server. The `paymentType` variable becomes the `PAYMENTACTION` parameter of the request string.

After the PayPal server returns the response, the code displays the API request and response in the browser. If the response from PayPal was a success, it displays the response parameters. If the response was an error, it displays the errors in APIError.php.

Called by DoDirectPayment.php.

Calls CallerService.php and APIError.php.

### Accepting PayPal in Express Checkout

This sample shows how to use Express Checkout to accept payments using PayPal. Access this sample from the following choices displayed on index.html:

ExpressCheckout - Sale | Do basic checkout with PayPal. In the `SetExpressCheckout` request, the `PAYMENTACTION` parameter is set to `Sale`.
ExpressCheckout - Authorization | Authorize for a single capture. In the `SetExpressCheckout` request, the `PAYMENTACTION` parameter is set to `Authorization`.
ExpressCheckout - Order | Authorize for multiple captures. In the `SetExpressCheckout` request, the `PAYMENTACTION` parameter is set to `Order`.

The primary files for this sample are:

File | Description
--- | ---

`SetExpressCheckout.php`

This is the main web page for the Express Checkout sample. The page allows the user to enter amount and currency type. It also accept input variable `paymentType` which becomes the value of the `PAYMENTACTION` parameter.

When the user clicks the Submit button, ReviewOrder.php is called.

Called by index.html.

Calls ReviewOrder.php.

`ReviewOrder.php`

This file is called after the user clicks on a button during the checkout process to use PayPal's Express Checkout. The user logs in to their PayPal account.

This file is called twice.

On the first pass, the code executes the if statement:

    if (! isset ($token))

The code collects transaction parameters from the form displayed by SetExpressCheckout.php then constructs and sends a `SetExpressCheckout` request string to the PayPal server. The `paymentType` variable becomes the `PAYMENTACTION` parameter of the request string. The `RETURNURL` parameter is set to this file; this is how ReviewOrder.php is called twice.

On the second pass, the code executes the else statement.

On the first pass, the buyer completed the authorization in their PayPal account; now the code gets the payer details by sending a `GetExpressCheckoutDetails` request to the PayPal server. Then the code calls GetExpressCheckoutDetails.php.

Note: Be sure to check the value of `PAYPAL_URL`. The buyer is sent to this URL to authorize payment with their PayPal account. For testing purposes, this should be set to the PayPal sandbox.

Called by SetExpressCheckout.php.

Calls GetExpressCheckoutDetails.php, CallerService.php, and APIError.php.

`GetExpressCheckoutDetails.php`

This functionality is called after the buyer returns from PayPal and has authorized the payment.

Displays the payer details returned by the `GetExpressCheckoutDetails` response and calls DoExpressCheckoutPayment.php to complete the payment authorization.

Called by ReviewOrder.php.

Calls DoExpressCheckoutPayment.php.

`DoExpressCheckoutPayment.php` | This functionality is called to complete the payment with PayPal and display the result to the buyer. The code constructs and sends the `DoExpressCheckoutPayment` request string to the PayPal server. Called by GetExpressCheckoutDetails.php. Calls CallerService.phpand APIError.php.

### Getting Transaction Details

This sample shows how to use the `GetTransactionDetails` request. Access this sample from the following choice displayed on index.html:

GetTransactionDetails | Gets transaction details for a specific transaction ID. The main page displays a text box where the user enters a transaction ID. When the user clicks the Submit button, the code constructs an NVP API request to `GetTransactionDetails` and sends it to the PayPal server.

The primary files for this sample are:

File | Description
--- | ---
`GetTransactionDetails.html` | This is the main page for GetTransactionDetails sample. This page displays a text box where the user enters a transaction ID and a Submit button that calls TransactionDetails.php. Called by index.html. Calls TransactionDetails.php.

`TransactionDetails.php`

Sends a `GetTransactionDetails` NVP API request to PayPal.

The code retrieves the transaction ID and constructs the NVP API request string to send to the PayPal server. The request to PayPal uses an API Signature.

After receiving the response from the PayPal server, the code displays the request and response in the browser. If the response was a success, it displays the response parameters. If the response was an error, it displays the errors received in APIError.php.

Called by GetTransactionDetails.html.

Calls CallerService.phpand APIError.php.

### DoCapture

This sample shows how to use the `DoCapture` request. Access this sample from the following choice displayed on index.html:

DoCapture

Settle an order or previously authorized transaction and obtain payment for either the complete amount or any portion of it.

The main page displays text boxes where the user enters a authorization ID,amount,invoice ID and drop downs where the user can select completecodetype,currency code. When the user clicks the Submit button, the code constructs an NVP API request to `DoCapture` and sends it to the PayPal server.

Note: DoCapture request is for use with both basic and order authorizations.

The primary files for this sample are:

File | Description
--- | ---

`DoCapture.php`

This is the main page for DoCapture sample. This page displays text boxes where the user enters a authorization ID,amount,invoice ID and drop down boxes where the user can select completecodetype,currency code. When the user clicks the Submit button that calls DoCaptureReceipt.php.

Called by index.html.

Calls DoCaptureReceipt.php.

`DoCaptureReceipt.php`

Sends a `DoCapture` NVP API request to PayPal.

The code retrieves the authorization ID,amount,invoice ID,completecodetype,currency code and constructs the NVP API request string to send to the PayPal server. The request to PayPal uses an API Signature.

After receiving the response from the PayPal server, the code displays the request and response in the browser. If the response was a success, it displays the response parameters. If the response was an error, it displays the errors received in APIError.php.

Called by DoCapture.php.

Calls CallerService.phpand APIError.php.

### DoVoid

This sample shows how to use the `DoVoid` request. Access this sample from the following choice displayed on index.html:

DoVoid

Void the authorization, if you need to cancel the transaction.

The main page displays text boxe where the user enters a authorization ID. When the user clicks the Submit button, the code constructs an NVP API request to `DoVoid` and sends it to the PayPal server.

IMPORTANT: The AuthorizationID value on DoVoid request must be the original authorization identification number, not the value of AuthorizationID returned by DoReauthorizationResponse.

By definition, when the authorization period expires, the authorization or reauthorization of a transaction is implicitly voided.

Note: DoVoid request is for use with both basic and order authorizations.

The primary files for this sample are:

File | Description
--- | ---
`DoVoid.php` | This is the main page for DoCapture sample. This page displays text boxe where the user enters a authorization ID. When the user clicks the Submit button that calls DoCaptureReceipt.php. Called by index.html. Calls DoVoidReceipt.php.

`DoVoidReceipt.php`

Sends a `DoVoid` NVP API request to PayPal.

The code retrieves the authorization ID and constructs the NVP API request string to send to the PayPal server. The request to PayPal uses an API Signature.

After receiving the response from the PayPal server, the code displays the request and response in the browser. If the response was a success, it displays the response parameters. If the response was an error, it displays the errors received in APIError.php.

Called by DoVoid.php.

Calls CallerService.phpand APIError.php.

### DoReauthorization

This sample shows how to use the `DoReauthorization` request. Access this sample from the following choice displayed on index.html:

DoReauthorization

Reauthorize for a different amount: You can reauthorize for up to 115% of the originally authorized amount, not to exceed an increase of $75 USD.

The main page displays text boxes where the user enters a authorization ID,amount and a drop down where the user can select currency code. When the user clicks the Submit button, the code constructs an NVP API request to `DoReauthorization` and sends it to the PayPal server.

To use DoReauthorization you must have previously authorized a transaction.

Note: DoReauthorizationRequest is for use only with basic authorizations, not order authorizations.

The primary files for this sample are:

File | Description
--- | ---

`DoReauthorization.html`

This is the main page for DoReauthorization sample. This page displays text boxes where the user enters a authorization ID,amount and drop down where the user can select currency code. When the user clicks the Submit button that calls DoReauthorizationReceipt.php.

Called by index.html.

Calls DoReauthorizationReceipt.php.

`DoReauthorizationReceipt.php`

Sends a `DoReauthorization` NVP API request to PayPal.

The code retrieves the authorization ID,amount,currency code and constructs the NVP API request string to send to the PayPal server. The request to PayPal uses an API Signature.

After receiving the response from the PayPal server, the code displays the request and response in the browser. If the response was a success, it displays the response parameters. If the response was an error, it displays the errors received in APIError.php.

Called by DoReauthorization.php.

Calls CallerService.phpand APIError.php.

### TransactionSearch

This sample shows how to use the `TransactionSearch` request. Access this sample from the following choice displayed on index.html:

TransactionSearch

Serching for a transaction.

The main page displays text boxes where the user enters a startdate,enddate and Transaction ID. When the user clicks the Submit button, the code constructs an NVP API request to `TransactionSearch` and sends it to the PayPal server.

With TransactionSearch request, you must always set the StartDate for your search.The effect of setting other elements is additive or can alter the search criteria.TransactionSearch response returns up to 100 exact matches.

The primary files for this sample are:

File | Description
--- | ---
`TransactionSearch.php` | This is the main page for TransactionSearch sample. This page displays text boxes where the user enters startdate,enddate and transaction ID. When the user clicks the Submit button that calls TransactionSearchResults.php. Called by index.html. Calls TransactionSearchResults.php.

`TransactionSearchResults.php`

Sends a `TransactionSearch` NVP API request to PayPal.

The code retrieves the startdate,enddate,transaction ID and constructs the NVP API request string to send to the PayPal server. The request to PayPal uses an API Signature.

After receiving the response from the PayPal server, the code displays the request and response in the browser. If the response was a success, it displays the response parameters. If the response was an error, it displays the errors received in APIError.php.

Called by TransactionSearch.php.

Calls CallerService.phpand APIError.php.

### RefundTransaction

This sample shows how to use the `RefundTransaction` request. Access this sample from the following choice displayed on index.html:

RefundTransaction

Use the RefundTransaction API to make either full or partial refunds.

The main page displays text boxes where the user enters a transaction ID,amount and drop downs where the user can select refund type,currency code. When the user clicks the Submit button, the code constructs an NVP API request to `RefundTransaction` and sends it to the PayPal server.

With RefundTransaction request, you must always pass the values of Transaction ID and RefundType. If RefundType is set to Full, you must not set Amount; however, if RefundType is Partial, you must set Amount.

The primary files for this sample are:

File | Description
--- | ---

`RefundTransaction.php`

This is the main page for RefundTransaction sample. This page displays text boxes where the user enters a transaction ID,amount and drop downs where the user can select refund type,currency code. When the user clicks the Submit button that calls RefundReceipt.php.

Called by index.html.

Calls RefundReceipt.php.

`RefundReceipt.php`

Sends a `RefundTransaction` NVP API request to PayPal.

The code retrieves the transaction ID,amount,refund type,currency code and constructs the NVP API request string to send to the PayPal server. The request to PayPal uses an API Signature.

After receiving the response from the PayPal server, the code displays the request and response in the browser. If the response was a success, it displays the response parameters. If the response was an error, it displays the errors received in APIError.php.

Called by RefundTransaction.php.

Calls CallerService.phpand APIError.php.

### MassPay

This sample shows how to use the `MassPay` request. Access this sample from the following choice displayed on index.html:

MassPay

The MassPay API is the programmatic counterpart to the Mass Payment feature available through the PayPal website. You can include up to 250 payments per MassPay request.The MassPay API triggers the sending of an Instant Payment Notification email to the recipient of the funds.

The main page displays text boxes where the user enters a emailsubject,recievertype,reciever email,amount,unique ID,note and drop down where the user can select currency code. When the user clicks the Submit button, the code constructs an NVP API request to `MassPay` and sends it to the PayPal server.

You must have a PayPal balance in each currency in which you want to make a payment and have sufficient funds to cover the entire Mass Payment amount and fee. You cannot mix currencies in the same MassPayRequest; a separate request is required for each currency.

The primary files for this sample are:

File | Description
--- | ---

`MassPay.html`

This is the main page for MassPay sample. This page displays text boxes where the user enters a emailsubject, recievertype,reciever email,amount,unique ID,note and drop down where the user can select currency code. When the user clicks the Submit button that calls MassPayReceipt.php.

Called by index.html.

Calls MassPayReceipt.php.

`MassPayReceipt.php`

Sends a `MassPay` NVP API request to PayPal.

The code retrieves the emailsubject,recievertype,reciever email,amount,unique ID,note,currency code and constructs the NVP API request string to send to the PayPal server. The request to PayPal uses an API Signature.

After receiving the response from the PayPal server, the code displays the request and response in the browser. If the response was a success, it displays the response parameters. If the response was an error, it displays the errors received in APIError.php.

Called by MassPay.html.

Calls CallerService.phpand APIError.php.

### Common Files

The following files are common to the samples.

File | Description
--- | ---
`index.html` | The main web page with links to each sample. Calls DoDirectPayment.php, SetExpressCheckout.php, and GetTransactionDetails.html.
`sdk.css` | Cascading Style Sheet (CSS) used by index.html.

`CallerService.php`

Each API uses this page to submit NVPRequest.

This Page reads the credential information from constants.php to connect with Server, submit NVPRequest and
return NVPResponse from the Server after de-formatting to display in response page.

Calls constants.php

Called by TransactionDetails.php, ReviewOrder.php,DoExpressCheckoutPayment.php and DoDirectPaymentReceipt.php.

`APIError.php` | Displays error parameters from the response in the browser. Called by DoDirectPaymentReceipt.php,TransactionDetails.php,ReviewOrder.php, DoExpressCheckoutPayment.php and CallerService.php.

`constants.php`

This is the configuration file for the samples.This file contains the parameters needed to make an API call and parameters needed for proxy setup.

PayPal includes the following API Signature for making API calls to the PayPal sandbox:

API Signature
API Username | `sdk-three_api1.sdk.com`
API Password | `QFZCWN5HZM8VBG7Q`
API Signature | `A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU`

Proxy Parameters
USE_PROXY | `Proxy will be enabled only when this set to TRUE.`
PROXY_HOST | `Proxy Server name or the IP address.`
PROXY_PORT | `Proxy Server port.`

Called by CallerService.php.

## API Documentation

The Name-Value Pair API Developer Guide and Reference is available in HTML and PDF format.

HTML | https://www.paypal.com/en_US/ebook/PP_NVPAPI_DeveloperGuide/index.html
PDF | https://www.paypal.com/en_US/pdf/PP_NVPAPI_DeveloperGuide.pdf