Calls, Headers, and Payment Types

Important: Adaptive Payments is not available for new integrations. PayPal provides this documentation to support existing integrations.

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, pre-approvals 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 use the 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 for 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 Gets information about a payment created with the Pay API operation.
ExecutePayment Executes a payment.
GetPaymentOptions Gets the settings specified with the SetPaymentOptions API operation.
SetPaymentOptions Sets payment options.
GetPrePaymentDisclosure Gets required disclosure information for certain foreign payments.

API operations for pre-approvals

API operation Description
Preapproval Sets up pre-approvals. A pre-approval is an approval to make future payments on the sender's behalf.
PreapprovalDetails Gets information about a pre-approval.
CancelPreapproval Cancels a pre-approval.

Other API operations

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

Adaptive Payments endpoints

The API operation and the environment in which you want to execute the API operation determines the endpoint.

For example, to send a Pay request to the sandbox endpoint, use this URL:

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

Use these 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 that specify:

  • Authentication credentials
  • The application ID
  • The device ID or IP address
  • The payload format or protocol (SOAP)

Adaptive Payments supports JSON, NVP, and XML-formatted request payloads.

You can specify different formats for the request and response.

For example, you can send the request in JSON and request an XML response.

For SOAP, you must also include a specific SOAP protocol header. See the SOAP messages topic.

This example shows 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 user name and API password. If you use 3-token authentication, you must also specify an API signature.

If you use a certificate, include the user name and password but do not include a signature.

To manage API certificates, see Create and manage NVP/SOAP API credentials.

To specify API credentials, include these HTTP headers in your request message:

Note: These headers are case sensitive.

Header Description
X-PAYPAL-SECURITY-USERID

The API user name.

X-PAYPAL-SECURITY-PASSWORD

The API password.

X-PAYPAL-SECURITY-SIGNATURE

The 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 call 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 pre-approval identified by a key, must be owned by the subject granting the third-party permission.

JSON, NVP, or XML data formats

To specify the data format the request body, use the HTTP X-PAYPAL-REQUEST-DATA-FORMAT header. Use JSON, NVP or straight XML to send messages.

To specify the data format for the response, use the X-PAYPAL-RESPONSE-DATA-FORMAT header.

Note: For the SOAP format, see SOAP messages.

Header Description
X-PAYPAL-REQUEST-DATA-FORMAT

The payload format for the request. Value is:

  • NV. Name-value pairs.
  • XML. Extensible markup language.
  • JSON. JavaScript object notation.
X-PAYPAL-RESPONSE-DATA-FORMAT

The payload format for the response. Value is:

  • 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");

The following Adaptive Payments WSDL shows the service name, port type, binding, and location for SOAP:

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

Application and device information

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

Header Required 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 PayPal sandbox Testing Guide.
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.

Make 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":"https://example.com/returnURL.htm", \
"requestEnvelope":{"errorLanguage":"en_US"},"currencyCode":"USD", \
"receiverList":{"receiver":[{"email":"david@example.com", \
"amount":"10.00",}]},"cancelUrl":"https://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.

Make 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=https://example.com/cancel
&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=https://example.com/return

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 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.

Make 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 following example, 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="">https://example.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="">https://example.com/returnURL.htm</returnUrl>
</PayRequest>

Pay response for chained payment

<?xml version='1.0' encoding='UTF-8'?>
<ns2:PayResponse xmlns:ns2="https://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 payment.

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