Calls, Headers, and Payment Types

These basic scenarios get you up and running quickly with the Adaptive Payments API. The sample code shows different combinations of requests with different bindings in various programming languages.

Adaptive Payments API Operations

Adaptive Payments provides API operations, enabling you to build an application that handles payments, preapprovals for payments, refunds, and additional operations related to payments. Some kinds of payments and operations require specific permission to use.

All Adaptive API calls in the Sandbox must have the following standard value as the App ID. When you use this standard value, all permissions are enabled by default, so you can test all types of integrations:

APP-80W284485P519543T

API Operations Related to Payments

API Operation Description
Pay Transfers funds from a sender's PayPal account to one or more receivers' PayPal accounts (up to 6 receivers)
PaymentDetails Obtains information about a payment created with the Pay API operation
ExecutePayment Executes a payment
GetPaymentOptions Obtain the settings specified with the SetPaymentOptions API operation
SetPaymentOptions Sets payment options
GetPrePaymentDisclosure Get required disclosure information for certain foreign payments

API Operations Related to Preapprovals

API Operation Description
Preapproval Sets up preapprovals, which is an approval to make future payments on the sender's behalf
PreapprovalDetails Obtains information about a preapproval
CancelPreapproval Cancels a preapproval

Other API Operations

API Operation Description
Refund Refunds all or part of a payment
ConvertCurrency Obtains the current foreign exchange (FX) rate for a specific amount and currency
GetFundingPlans Determines the funding sources that are available for a specified payment
GetShippingAddresses Obtains the selected shipping address

Adaptive Payments Endpoints

The endpoint is determined by the API operation and the environment in which you want to execute the API operation. For example, if you want to send a Pay request to the sandbox endpoint, specify the following URL:

https://svcs.sandbox.paypal.com/AdaptivePayments/Pay

You can specify the following endpoints:

Environment Endpoint
Production
https://svcs.paypal.com/AdaptivePayments/API_operation
Sandbox
https://svcs.sandbox.paypal.com/AdaptivePayments/API_operation

HTTP Headers

Each request message includes HTTP headers specifying authentication, the application ID, the device ID or IP address, and the payload format or protocol (SOAP).

Adaptive Payments supports request payloads in JSON, NVP, and XML formats. You can specify different formats for the request and response, such as sending the request in JSON and requesting an XML response.

For SOAP, you must also include a specific SOAP protocol header (see the SOAP messages section).

The following is an example of HTTP headers for NVP in Java for a web implementation:

headers.put("X-PAYPAL-SECURITY-USERID", "tok261_biz_api.abc.com");
headers.put("X-PAYPAL-SECURITY-PASSWORD","1244612379");
headers.put("X-PAYPAL-SECURITY-SIGNATURE","lkfg9groingghb4uw5"
headers.put("X-PAYPAL-DEVICE-IPADDRESS", "168.212.226.204");
headers.put("X-PAYPAL-REQUEST-DATA-FORMAT", "NV");
headers.put("X-PAYPAL-RESPONSE-DATA-FORMAT", "NV");
headers.put("X-PAYPAL-APPLICATION-ID", "APP-80W284485P519543T");
Note: HTTP headers are case sensitive.

Authentication

Use your PayPal account API credentials to authenticate your application. Your API credentials include an API username and API password. If you are using 3-token authentication, you must also specify an API signature.

If you are using a certificate, the certificate is used with the username and password. The signature is not used. To manage API certificates, see Creating and Managing Classic API Credentials.

To specify API credentials, include the following HTTP headers in your request message (observing case sensitivity):

Table 1. HTTP Headers for Authentication
Header Description
X-PAYPAL-SECURITY-USERID Your API username
X-PAYPAL-SECURITY-PASSWORD Your API password
X-PAYPAL-SECURITY-SIGNATURE Your API signature, which is required only if you use 3-token authorization; a certificate does not use a signature
X-PAYPAL-SECURITY-SUBJECT Third-party permission specification, which specifies the email address or phone number (for mobile) of the party on whose behalf you are calling the API operation. The subject must grant you third-party access in their PayPal profile.
Note: Resources specified by the API operation, such as a payment or preapproval identified by a key, must be owned by the subject granting the third-party permission.

Specifying JSON, NVP, or XML Data Formats

Use the HTTP header X-PAYPAL-REQUEST-DATA-FORMAT to specify the data format the request body. You can send messages using JSON, NVP or straight XML. Use the and X-PAYPAL-RESPONSE-DATA-FORMAT headers to specify the data format for the response. For SOAP messages, refer to the next section.

Table 2. HTTP Headers for JSON, NVP, and XML Data Formats
Header Description
X-PAYPAL-REQUEST-DATA-FORMAT The payload format for the request. Allowable values are:
  • NV – Name-value pairs
  • XML – Extensible markup language
  • JSON – JavaScript object notation
X-PAYPAL-RESPONSE-DATA-FORMAT The payload format for the response. Allowable values are:
  • NV – Name-value pairs
  • XML – Extensible markup language
  • JSON – JavaScript object notation

SOAP Messages

To use Adaptive Payments with SOAP, include the HTTP headers for authentication as described in the section Authentication and the application ID as described in the next section. In addition, include the X-PAYPAL-MESSAGE-PROTOCOL header with a SOAP11 value.
The following is a header example for an Adaptive Payments API call for a SOAP message:

headers.put("X-PAYPAL-SECURITY-USERID", "tok261_biz_api.abc.com");
headers.put("X-PAYPAL-SECURITY-PASSWORD","1244612379");
headers.put("X-PAYPAL-SECURITY-SIGNATURE","lkfg9groingghb4uw5"
headers.put("X-PAYPAL-DEVICE-IPADDRESS", "168.212.226.204");
headers.put("X-PAYPAL-MESSAGE-PROTOCOL", "SOAP11");
headers.put("X-PAYPAL-APPLICATION-ID","APP-80W284485P519543T");

Below are the service name, port type, binding and location for SOAP as defined in the Adaptive Payments WSDL.

<wsdl:service name="AdaptivePayments">
<wsdl:port name="AdaptivePaymentsSOAP11_http"
<binding="services:AdaptivePaymentsSOAP11Binding">
<soap:address location="https://svcs.paypal.com/AdaptivePayments" />

Specifying Application and Device Information

You also must identify the application. You can optionally identify other information associated with the client and the API version:

Table 3. HTTP Headers for Application and Device identification
Header Description
X-PAYPAL-APPLICATION-ID (Required) Your application's identification, which is issued by PayPal.
Note: For the application ID (app ID) for the sandbox, see Testing Classic API Calls.
X-PAYPAL-DEVICE-ID (Optional) Client's device ID, such as a mobile device's IMEI number or a web browser cookie.
X-PAYPAL-DEVICE-IPADDRESS (Required) Client's IP address.
X-PAYPAL-SERVICE-VERSION (Optional) The version of an API operation to use. By default, PayPal executes a request with the current version of an API operation.
Note: PayPal recommends not specifying a version unless it is absolutely required.

Making a Simple Payment (JSON)

A simple payment is when a sender (whose account is debited) sends a payment (amount and currency) to a single receiver (whose account is credited).

  • You send a PayRequest message to PayPal
  • You receive a response with a pay key.
  • You must redirect the sender's browser to PayPal to approve the payment.

Pay Request for Simple Payment

{"returnUrl":"http://example.com/returnURL.htm", \
"requestEnvelope":{"errorLanguage":"en_US"},"currencyCode":"USD", \
"receiverList":{"receiver":[{"email":"david@example.com", \
"amount":"10.00",}]},"cancelUrl":"http://example.com/cancelURL.htm",\
"actionType":"PAY"}

Pay Response for Simple Payment

{"responseEnvelope":\
{"timestamp":"2009-10-06T14:30:39.383-07:00","ack":"Success",\
"correlationId":"cfe8f8783f1d3","build":"DEV"},\
"payKey":"AP-17266198048308436","paymentExecStatus":"CREATED"}

The response includes a pay key, which is a token you use in subsequent calls to Adaptive Payments APIs to identify this particular payment. In this particular scenario, the paymentExecStatus variable is set to CREATED instead of COMPLETED, which indicates that the payment has been created, but has not yet been executed.

Making a Parallel Payment (NVP)

A parallel payment is when a sender (whose account is debited) sends a single payment (amount and currency) up to 6 receivers. The sender can see each payment to a receiver.

  • You send a PayRequest, specifying an amount to be paid for each receiver.
  • You receive a response with a pay key.
  • You must redirect the sender's browser to PayPal to approve the payment.

In the example below, Paul makes a single payment of $14, which is split into a $9 payment to Andrea and a $5 payment to Linda. The following event sequence takes place:

Pay Request for Parallel Payment

&actionType=PAY
&cancelUrl=http:\\example.com\cancel.htm
&currencyCode=USD
&receiverList.receiver(0).amount=9.00
&receiverList.receiver(0).email=andrea@example.com
&receiverList.receiver(1).amount=5.00
&receiverList.receiver(1).email=linda@example.com
&requestEnvelope.errorLanguage=en_US
&returnUrl=http:\\example.com\return.htm

Pay Response for Parallel Payment

responseEnvelope.timestamp=2009-11-03T08%3A12.937-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=b1cc3eabfa4c1
&responseEnvelope.build=942345
&payKey=AP-688241038Y786593D
&paymentExecStatus=CREATED

The response includes a pay key, which is a token you use in subsequent calls to Adaptive Payments APIs to identify this particular payment. In this particular scenario, the paymentExecStatus variable is set to CREATED instead of COMPLETED, which indicates that the payment has been created, but has not yet been executed.

Making a Chained Payment (XML)

A chained payment is when a sender sends a payment to a PayPal-registered receiver who is the primary receiver.

  • You send a PayRequest, enabling the primary receiver.
  • You receive a response with a pay key.
  • You must redirect the sender's browser to PayPal to approve the payment.

With chained payments, the sender only sees the transaction to the primary API caller. The receiver only sees the transaction from the primary API caller. The transactions from and to the receivers are hidden from the sender and receivers.

In the example below, Tim makes a single payment of $100 to Frank, who is the primary receiver. Of this amount, Frank keeps $25 and pays Yvonne $75. The following event sequence takes place:

Pay Request for Chained Payment

<PayRequest>
<requestEnvelope>
<errorLanguage>en_US</errorLanguage> </requestEnvelope>
<cancelUrl xmlns="">http://exammple.com/cancelURL.htm</cancelUrl>
<actionType>PAY</actionType>
<currencyCode xmlns="">USD</currencyCode>
<receiverList xmlns="">
<receiver>
<amount>100</amount>
<email>frank@example.com</email>
<primary>true</primary>
</receiver>
<receiver>
<amount>75</amount>
<email>yvonne@example.com</email>
<primary>false</primary>
</receiver>
</receiverList>
<returnUrl xmlns="">http://example.com/returnURL.htm</returnUrl>
</PayRequest>

Pay Response for Chained Payment

<?xml version='1.0' encoding='UTF-8'?>
<ns2:PayResponse xmlns:ns2="http://svcs.paypal.com/types/ap">
<responseEnvelope>
<timestamp>2009-10-06T17:24:03.874-07:00</timestamp>
<ack>Success</ack><correlationId>eca3a204200f4</correlationId>
<build>1044393</build></responseEnvelope>
<payKey>AP-688241038Y786593D</payKey>
<paymentExecStatus>CREATED</paymentExecStatus></ns2:PayResponse>

The response includes a pay key, which is a token you use in subsequent calls to Adaptive Payments APIs to identify this particular payment.

In this particular scenario, the paymentExecStatus variable is set to CREATED instead of COMPLETED, which indicates that the payment has been created, but has not yet been executed.