Adaptive Payments API: Getting Started

Get up and running with the Adaptive Payments API:

Overview

The Adaptive Payments API enables merchants and developers to select the payment scenario most suitable to their needs.

Merchants and developers can create applications that manage payments, payment pre-approvals, and refunds. Merchants and developers also can send money peer-to-peer, and can split payments in both the parallel and the chained models. Merchants and developers can accept guest payments and can schedule disbursements.

The Adaptive Payments API works on multiple platforms, including the web and mobile platforms.

Key concepts

Adaptive Payments operations enable the sending and receiving of payments involving two or more parties. Each Adaptive Payments API transaction includes a sender and one or more receivers of the payment. Each transaction also includes the application owner, or API caller, who is an invisible third party that provides the transaction flow and makes the API calls.

In most scenarios, the buyer initiates send type of payment transactions and the seller initiates pay type of payment transactions.

The Adaptive Payments API uses the Pay operation to make payments between a sender and one or more receivers of that payment. Payments can be split between receivers (in either "chained" or "parallel" modes) and additional operations in the API lets senders authorize and pre-approve an application to make payments on their behalf. The flexibility of the operations in the API make for an "adaptive" set of functions that addresses a wide range of payment scenarios.

Payment approvals

As with any payment, payments made through the Adaptive Payments API must be authorized and approved by the payment sender. To provide the best possible user experience for senders, the Adaptive Payments API provides the following payment approval methods:

<dl>
<dt>Web Redirect</dt>
<dd>The default method where applications redirect the sender of the payment to PayPal for approval.</dd>
<dt>Embedded Process</dt>
<dd>Applications embed the payment authorization process into the application itself.</dd>
<dt>Implicit</dt>
<dd>Applications act as the sender of the payment and _implicitly_ authorize the payment.</dd>
<dt>Preapproved</dt>
<dd>Applications obtain a pre-approval from the sender.</dd>
</dl>

Make your first call

To call the Adaptive Payments Pay operation, supply the necessary HTTP headers and the call payload to the service endpoint.

A call to the Pay operation involves these users:

To make the Pay call and authorize the payment after the Pay operation succeeds:

That's it. You're now set to make the call.

Try it

The following cURL command contains a call to the Pay operation. Run the command by copying and pasting it into a code window. (If cURL is not installed on your system, you can download the free cURL executable from https://curl.haxx.se/download.html.)

curl https://svcs.sandbox.paypal.com/AdaptivePayments/Pay \
  -s \
  --insecure \
  -H "X-PAYPAL-SECURITY-USERID: caller_1312486258_biz_api1.gmail.com" \
  -H "X-PAYPAL-SECURITY-PASSWORD: 1312486294" \
  -H "X-PAYPAL-SECURITY-SIGNATURE: AbtI7HV1xB428VygBUcIhARzxch4AL65.T18CTeylixNNxDZUu0iO87e" \
  -H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-APPLICATION-ID: APP-80W284485P519543T" \
  -d '{
  "actionType": "PAY",
  "currencyCode": "USD",
  "receiverList": {
    "receiver": [{
      "amount": "1.00",
      "email": "rec1_1312486368_biz@gmail.com"
    }]
  },
  "returnUrl": "https://example.com/success.html",
  "cancelUrl": "https://example.com/failure.html",
  "requestEnvelope": {
    "errorLanguage": "en_US",
    "detailLevel": "ReturnAll"
  }
}'

You have made your first call to the Adaptive Payments API.

After you issue the command, the Adaptive Payments service returns a successful response that includes a valid sandbox payKey.

The previous call is made possible by the use of a publicly-available set of sandbox credentials (highlighted in the call). While you can extract the payKey from the response and use it in an authorization redirect, you cannot authorize the sandbox transaction. However, if you substitute the credentials and e-mail address from your sandbox accounts into the previous command, you can complete the entire transaction flow in the sandbox.

If your Pay call fails with your own sandbox credentials, review the call response for the error details and address the problem before you resubmit the call. If your call succeeds, insert the returned payKey value into this URL:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_ap-payment&paykey=<Your-payKey>

Log in to the PayPal window with your sandbox buyer account credentials to complete the transaction. Then, log in to your sandbox account and review the account balances and e-mail to see the transaction results.

Next steps

Use these suggestions to enhance your understanding of the Adaptive Payments API: