NVP API Web Samples Using PHP

VERSION 5.1.56

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

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.

Descriptions of Samples

The web samples consist of the following:

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 boxes 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 Searching 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,receivertype,receiver 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