> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a PayPal Deposit Preauthorization

This endpoint creates a [Deposit Preauthorization](/api-reference/deposit-preauthorizations/deposit-preauthorization-object) with `PaymentType` of `PAYPAL` and returns the PayPal `RedirectURL` on which the user can preauthorize the debited funds.

Once authorized (`Status` becomes `SUCCEEDED`), you can capture the funds using the [POST Create a Deposit Preauthorized PayIn](/api-reference/deposit-preauthorizations/create-deposit-preauthorized-payin) endpoint.

<Check>
  **Best practice - Capture funds within 3 days**

  PayPal recommends that you capture preauthorized funds within 3 days (using [POST Create a Preauthorized PayPal PayIn](/api-reference/paypal/create-preauthorized-paypal-payin)). This is because the success of the capture is subject to risk and the availability of funds on the card (or other funding instrument) that the user has linked to their PayPal account.
</Check>

### Body parameters

<ParamField body="AuthorId" type="string" required>
  The unique identifier of the user at the source of the transaction.
</ParamField>

<ParamField body="DebitedFunds" type="object" required>
  Information about the preauthorized funds.

  <Expandable title="properties">
    <ParamField body="Currency" type="string" required>
      **Allowed values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).

      The currency of the funds.
    </ParamField>

    <ParamField body="Amount" type="integer" required>
      An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="ReturnURL" type="string" required>
  Max. length: 255 characters

  The URL to which the user is returned after the payment, whether the transaction is successful or not.
</ParamField>

<ParamField body="CancelURL" type="string">
  The URL to which the user is returned after canceling the payment. If not provided, the Cancel button returns the user to the `RedirectURL`.
</ParamField>

<ParamField body="DataCollectionId" type="string">
  The unique identifier of the Data Collection object containing the data sent for this pay-in via the [POST Submit data for a PayPal PayIn](/api-reference/paypal/submit-data-paypal-payin) endpoint.

  Each PayPal pay-in or preauth requires a new `DataCollectionId`. The property is not returned on the pay-in endpoints.
</ParamField>

<ParamField body="ShippingPreference" type="string">
  **Allowed values:** `SET_PROVIDED_ADDRESS`, `GET_FROM_FILE`, `NO_SHIPPING`

  Information about the shipping address behavior on the PayPal payment page:

  * `SET_PROVIDED_ADDRESS` - The `Shipping` parameter becomes required and its values are displayed to the end user, who is not able to modify them.
  * `GET_FROM_FILE` – The `Shipping` parameter is ignored and the end user can choose from registered addresses.
  * `NO_SHIPPING` – No shipping address section is displayed.
</ParamField>

<ParamField body="Shipping" type="object">
  Required if `ShippingPreference` is `SET_PROVIDED_ADDRESS`.

  Information about the end user’s shipping address, managed by `ShippingPreference`.

  <Expandable title="properties">
    <ParamField body="FirstName" type="string">
      The first name of the user.
    </ParamField>

    <ParamField body="LastName" type="string">
      Max. length: 100 characters

      The last name of the user.
    </ParamField>

    <ParamField body="Address" type="object" required>
      Information about the shipping address.

      <Expandable title="properties">
        <ParamField body="AddressLine1" type="string" required>
          Max. length: 255 characters

          The first line of the address.
        </ParamField>

        <ParamField body="AddressLine2" type="string">
          Max. length: 255 characters

          The second line of the address.
        </ParamField>

        <ParamField body="City" type="string" required>
          Max. length: 255 characters

          The city of the address.
        </ParamField>

        <ParamField body="Region" type="string">
          Max. length: 255 characters

          Required if `Country` is US, CA, or MX.

          The region of the address.
        </ParamField>

        <ParamField body="PostalCode" type="string" required>
          Max. length: 255 characters

          The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.
        </ParamField>

        <ParamField body="Country" type="string" required>
          Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))

          The country of the address.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="Reference" type="string">
  Max. length: 127 characters (truncated after)

  The platform’s order reference for the transaction.
</ParamField>

<ParamField body="Tag" type="string">
  Max. length: 255 characters

  Custom data that you can add to this object.\
  For transactions (pay-in, transfer, payout), you can use this parameter to identify corresponding information regarding the user, transaction, or payment methods on your platform.
</ParamField>

<ParamField body="StatementDescriptor" type="string">
  Max. length: 10 characters; only alphanumeric and spaces

  Custom description to appear on the user’s bank statement along with the platform name. Different banks may show more or less information. See the <a href="/bank-statements">Customizing bank statement references</a> article for details.
</ParamField>

<ParamField body="Culture" type="string">
  **Allowed values:** One of the supported languages in the <a href="/api-reference/overview/data-formats">ISO 639-1 format</a>: AT, BR, CA, CH, CN, DE, DK, ES, FR, GB, ID, IL, IT, JK, JP, NL, NO, PL, PT, RU, SE, TH, TR, TW, US.

  The language in which the PayPal payment page is to be displayed.
</ParamField>

<ParamField body="ProfilingAttemptReference" type="string">
  The unique reference generated for the profiling session, used by the <a href="/guides/fraud-prevention">fraud prevention</a> solution to produce recommendations for the transaction using the profiling data.

  **Note:** Parameter not returned by the API. Profiling feature available on request – contact Mangopay <a href="https://hub.mangopay.com/" target="_blank">via the Dashboard</a> for more information.
</ParamField>

### Responses

<AccordionGroup>
  <Accordion title="200">
    <ResponseField name="ShippingPreference" type="string">
      **Returned values:** `SET_PROVIDED_ADDRESS`, `GET_FROM_FILE`, `NO_SHIPPING`

      Information about the shipping address behavior on the PayPal payment page:

      * `SET_PROVIDED_ADDRESS` - The `Shipping` parameter becomes required and its values are displayed to the end user, who is not able to modify them.
      * `GET_FROM_FILE` – The `Shipping` parameter is ignored and the end user can choose from registered addresses.
      * `NO_SHIPPING` – No shipping address section is displayed.
    </ResponseField>

    <ResponseField name="PaypalBuyerAccountEmail" type="string">
      The email address registered on the PayPal account used to make the payment.
    </ResponseField>

    <ResponseField name="Reference" type="string">
      Max. length: 127 characters (truncated after)

      The platform’s order reference for the transaction.
    </ResponseField>

    <ResponseField name="CancelURL" type="string">
      The URL to which the user is returned after canceling the payment. If not provided, the Cancel button returns the user to the RedirectURL.
    </ResponseField>

    <ResponseField name="PaypalOrderID" type="string">
      PayPal's unique identifier for the order.
    </ResponseField>

    <ResponseField name="BuyerFirstname" type="string">
      The first name of the buyer.
    </ResponseField>

    <ResponseField name="BuyerPhone" type="string">
      The mobile phone number of the buyer.
    </ResponseField>

    <ResponseField name="BuyerCountry" type="string">
      The country of the buyer.
    </ResponseField>

    <ResponseField name="BuyerLastname" type="string">
      The last name of the buyer.
    </ResponseField>

    <ResponseField name="PaypalPayerID" type="string">
      The PayPal identifier of the buyer.
    </ResponseField>

    <ResponseField name="Trackings" type="array (object)">
      Shipping information of the `LineItems` added to the pay-in object.

      <Expandable title="properties">
        <ResponseField name="TrackingNumber" type="string">
          The shipment’s tracking number provided by the carrier.
        </ResponseField>

        <ResponseField name="Carrier" type="string">
          The carrier for the shipment. Use the country-specific version of the carrier if it exists, otherwise use its global version.
        </ResponseField>

        <ResponseField name="NotifyBuyer" type="string">
          **Default value:** false

          If `true`, sends an email notification to the `PaypalBuyerAccountEmail` containing the `TrackingNumber` and `Carrier`, which allows the end user to track their shipment with the carrier.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Id" type="string">
      Max. length: 255 characters

      The unique identifier of the PayPal preauthorization.
    </ResponseField>

    <ResponseField name="CreationDate" type="Unix timestamp">
      The date and time at which the object was created.
    </ResponseField>

    <ResponseField name="ExpirationDate" type="Unix timestamp">
      The date and time at which the hold period ends and the preauthorized funds are released.\
      At the expiration date, the deposit preauthorization’s `PaymentStatus` changes to `EXPIRED` if no captures were made.
    </ResponseField>

    <ResponseField name="AuthorId" type="string">
      The unique identifier of the user at the source of the transaction.
    </ResponseField>

    <ResponseField name="DebitedFunds" type="object">
      Information about the preauthorized funds.

      <Expandable title="properties">
        <ResponseField name="Currency" type="string">
          **Returned values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).

          The currency of the funds.
        </ResponseField>

        <ResponseField name="Amount" type="integer">
          An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Status" type="string">
      **Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`

      The status of the authorization.
    </ResponseField>

    <ResponseField name="PaymentStatus" type="string">
      **Returned values:** `WAITING`, `CANCELED`, `CANCEL_REQUESTED`, `EXPIRED`, `VALIDATED`, `FAILED`

      The payment status of the deposit preauthorization object:

      * `WAITING` – The deposit preauthorization can be used: the preauthorized funds can be captured (if `Status` is `SUCCEEDED`) or the preauthorization can be canceled manually.
      * `CANCELED` – Value to pass to manually cancel the deposit preauthorization before use; indicates that the deposit preauthorization was canceled manually.
      * `CANCEL_REQUESTED` – The cancellation of the deposit preauthorization has been requested but not yet processed.
      * `EXPIRED` – The hold period on the preauthorized funds has ended without it being used.
      * `VALIDATED` – Indicates that the preauthorized funds were captured.
      * `FAILED` – The pay-in against the preauthorization has failed, but a retry may be possible.
    </ResponseField>

    <ResponseField name="PayinsLinked" type="object">
      Information about the deposit preauthorized pay-ins made against the deposit preauthorization.

      <Expandable>
        <ResponseField name="PayinCaptureId" type="string">
          The unique identifier of the preauthorized pay-in (capture) made against the deposit preauthorization to debit the preauthorized funds.
        </ResponseField>

        <ResponseField name="PayinComplementId" type="string" deprecated>
          This deprecated parameter is always returned `null`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ResultCode" type="string">
      The code indicating the result of the operation. This information is mostly used to <a href="/errors/codes">handle errors</a> or for filtering purposes.
    </ResponseField>

    <ResponseField name="ResultMessage" type="string">
      The explanation of the result code.
    </ResponseField>

    <ResponseField name="PaymentType" type="string">
      **Returned values:** `PAYPAL`

      The type of pay-in.
    </ResponseField>

    <ResponseField name="ExecutionType" type="string">
      **Returned values:** `WEB`, `DIRECT`, `EXTERNAL_INSTRUCTION`

      The type of execution for the pay-in.
    </ResponseField>

    <ResponseField name="StatementDescriptor" type="string">
      Max. length: 10 characters; only alphanumeric and spaces

      Custom description to appear on the user’s bank statement along with the platform name. Different banks may show more or less information. See the <a href="/bank-statements">Customizing bank statement references</a> article for details.
    </ResponseField>

    <ResponseField name="Culture" type="string">
      **Returned values:** One of the supported languages in the <a href="/api-reference/overview/data-formats">ISO 639-1 format</a>: AT, BR, CA, CH, CN, DE, DK, ES, FR, GB, ID, IL, IT, JK, JP, NL, NO, PL, PT, RU, SE, TH, TR, TW, US.

      The language in which the PayPal payment page is to be displayed.
    </ResponseField>

    <ResponseField name="Billing" type="object" null>
      Returned `null` because the billing address is not applicable to PayPal preauth.
    </ResponseField>

    <ResponseField name="Shipping" type="object">
      Information about the end user’s shipping address, managed by `ShippingPreference`.

      <Expandable title="properties">
        <ResponseField name="FirstName" type="string">
          The first name of the user.
        </ResponseField>

        <ResponseField name="LastName" type="string">
          Max. length: 100 characters

          The last name of the user.
        </ResponseField>

        <ResponseField name="Address" type="object">
          Information about the shipping address.

          <Expandable title="properties">
            <ResponseField name="AddressLine1" type="string">
              Max. length: 255 characters

              The first line of the address.
            </ResponseField>

            <ResponseField name="AddressLine2" type="string">
              Max. length: 255 characters

              The second line of the address.
            </ResponseField>

            <ResponseField name="City" type="string">
              Max. length: 255 characters

              The city of the address.
            </ResponseField>

            <ResponseField name="Region" type="string">
              Max. length: 255 characters

              The region of the address. This field is optional except if the `Country` is US, CA, or MX.
            </ResponseField>

            <ResponseField name="PostalCode" type="string">
              Max. length: 255 characters

              The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.
            </ResponseField>

            <ResponseField name="Country" type="string">
              Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))

              The country of the address.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Tag" type="string">
      Max. length: 255 characters

      Custom data that you can add to this object.\
      For transactions (pay-in, transfer, payout), you can use this parameter to identify corresponding information regarding the user, transaction, or payment methods on your platform.
    </ResponseField>
  </Accordion>
</AccordionGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
      "ShippingPreference": "SET_PROVIDED_ADDRESS",
      "PaypalBuyerAccountEmail": null,
      "Reference": "1234",
      "CancelURL": "http://www.example.net/?depositId=deposit_wt_05e5e212-fa97-4d67-8c5e-1495eb91d8b4",
      "PaypalPayerID": null,
      "BuyerCountry": null,
      "BuyerFirstname": null,
      "BuyerLastname": null,
      "BuyerPhone": null,
      "PaypalOrderID": "6L593294612936822",
      "Trackings": null,
      "LineItems": [
          {
              "Name": "Running shoes",
              "Quantity": 1,
              "UnitAmount": 1000,
              "TaxAmount": 0,
              "Description": "ID of Seller 1",
              "Category": "PHYSICAL_GOODS",
              "Sku": null,
              "Discount": 0
          }
      ],
      "Id": "deposit_wt_05e5e212-fa97-4d67-8c5e-1495eb91d8b4",
      "CreationDate": 1774263809,
      "ExpirationDate": 1776855809,
      "AuthorId": "user_m_01KMD5PX2KPDVQ0C37XR375MPP",
      "DebitedFunds": {
          "Currency": "GBP",
          "Amount": 1000
      },
      "Status": "CREATED",
      "PaymentStatus": "WAITING",
      "PayinsLinked": {
          "PayinCaptureId": null,
          "PayinComplementId": null
      },
      "ResultCode": null,
      "ResultMessage": null,
      "PaymentType": "PAYPAL",
      "ExecutionType": "WEB",
      "StatementDescriptor": "Example123",
      "Culture": "EN",
      "Billing": null,
      "Shipping": {
          "FirstName": "Alex",
          "LastName": "Smith",
          "Address": {
              "AddressLine1": "10 Kingsway",
              "City": "London",
              "Region": null,
              "PostalCode": "WC2B 6LH",
              "Country": "GB"
          }
      },
      "Tag": "Created using the Mangopay API Postman collection",
      "RedirectURL": "https://www.paypal.com/checkoutnow?token=6L593294612936822",
      "ReturnURL": "https://www.example.com/?depositId=deposit_wt_05e5e212-fa97-4d67-8c5e-1495eb91d8b4"
  }
  ```
</ResponseExample>

<RequestExample>
  ```json REST theme={null}
  {
      "Tag": "Created using the Mangopay API Postman collection",
      "AuthorId": "user_m_01KHXAHEBRWSZXJY85TPPR56TK",
      "DebitedFunds": {
          "Currency": "GBP",
          "Amount": 1000
      },
      "ReturnURL": "https://www.example.com",
      "CancelURL": "https://www.example.net",
      "StatementDescriptor": "Example123",
      "Shipping": {
          "FirstName": "Alex",
          "LastName": "Smith",
          "Address": {
              "AddressLine1": "10 Kingsway",
              "City": "London",
              "Region": null,
              "PostalCode": "WC2B 6LH",
              "Country": "GB"
          }
      },
      "LineItems": [
          {
              "Name": "Running shoes",
              "Quantity": "1",
              "UnitAmount": 1000,
              "TaxAmount": 0,
              "Description": "ID of Seller 1",
              "Category": "PHYSICAL_GOODS"
          }
      ],
      "Culture": "EN",
      "ShippingPreference": "SET_PROVIDED_ADDRESS",
      "Reference": "1234",
      "DataCollectionId": "77b23645-dba3-4948-a5ba-32a134a3148d"
  }
  ```
</RequestExample>