# Calls, Headers, and Payment Types (/archive/adaptive-payments/integration-guide/APCallsHeadersAndPaymentTypes) > **Note:** **Important:** Adaptive Payments is not available for new > integrations. PayPal provides this documentation to support existing > integrations. If you're starting an integration, > [we recommend our latest solutions](https://www.paypal.com/us/business/accept-payments). 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-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:
```text lineNumbers APP-80W284485P519543T ``` ### API operations for payments [#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-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 [#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 [#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:
```html lineNumbers 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 [#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:
```text lineNumbers 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:** **Note:** HTTP headers are case sensitive. ### Authentication [#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](/api/nvp-soap/apiCredentials/). To specify API credentials, include these HTTP headers in your request message: > **Note:** **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:** **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 [#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:** **Note:** For the SOAP format, see > [SOAP messages](#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 [#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:
```text lineNumbers 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:
```html lineNumbers ``` ### Application and device information [#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:** **Note:** For the application ID (app ID) for the sandbox, see [PayPal sandbox Testing Guide](/sandbox-testing/overview). | | `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:** **Note:** PayPal recommends not specifying a version unless it is absolutely required. | ## Make a simple payment (JSON) [#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 [#pay-request-for-simple-payment]
```text lineNumbers {"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 [#pay-response-for-simple-payment]
```text lineNumbers {"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) [#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 [#pay-request-for-parallel-payment]
```text lineNumbers &actionType=PAY &cancelUrl=https://example.com/cancel ¤cyCode=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 [#pay-response-for-parallel-payment]
```text lineNumbers 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) [#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 [#pay-request-for-chained-payment]
```html lineNumbers en_US https://example.com/cancelURL.htm PAY USD 100 frank@example.com true 75 yvonne@example.com false https://example.com/returnURL.htm ``` ### Pay response for chained payment [#pay-response-for-chained-payment]
```html lineNumbers 2009-10-06T17:24:03.874-07:00 Successeca3a204200f4 1044393 AP-688241038Y786593D CREATED ``` 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.