Test and go live

You can run negative tests on your integration to manage the responses you give to your customers.

Know before you code

• Before you trigger a simulation, you'll need to you need to get an access token.

• Use Postman to explore and test PayPal APIs.

Simulation methods

To trigger a simulation for the Payouts API, use a JSON pointer in the request payload or use a path parameter in the request URI.

Use a JSON pointer in the request payload

JSON pointer request

curl -X POST https://api-m.sandbox.paypal.com/v1/payments/payouts \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <Access-Token>" \
  -d '{
  "sender_batch_header":
  {
    "sender_batch_id": "1524086406556",
    "email_subject": "This email is related to simulation"
  },
  "items": [
  {
    "recipient_type": "EMAIL",
    "receiver": "payouts-simulator-receiver@paypal.com",
    "note": "ERRPYO002",
    "sender_item_id": "15240864065560",
    "amount":
    {
      "currency": "USD",
      "value": "1.00"
    }
  }]
}'

JSON pointer response

{
  "name": "SENDER_EMAIL_UNCONFIRMED",
  "message": "Authorization error occurred",
  "debug_id": "ca787bdf80d7a",
  "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch/v1/#errors"
}

Use a path parameter in the request URI

Path parameter request

curl -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/ERRPYO015 \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <Access-Token>"

Path parameter response

{
  "batch_header":
  {
    "payout_batch_id": "DQCP2UAJCBMNY",
    "batch_status": "SUCCESS",
    "time_created": "2017-08-21T11:22:33Z",
    "time_completed": "2017-08-21T11:22:54Z",
    "sender_batch_header":
    {
      "email_subject": "user test case"
    },
    "amount":
    {
      "currency": "USD",
      "value": "190.0"
    },
    "fees":
    {
      "currency": "USD",
      "value": "0.0"
    }
  },
  "items": [
  {
    "payout_item_id": "RWD4Y3H9VV8BA",
    "transaction_status": "FAILED",
    "payout_item_fee":
    {
      "currency": "USD",
      "value": "0.0"
    },
    "payout_batch_id": "DQCP2UAJCBMNY",
    "payout_item":
    {
      "recipient_type": "EMAIL",
      "amount":
      {
        "currency": "USD",
        "value": "190.0"
      },
      "note": "payout to  receiver",
      "receiver": "receiver@example.com",
      "sender_item_id": "MSI-2727"
    },
    "time_processed": "2017-08-21T11:22:44Z",
    "errors":
    {
      "name": "CLOSED_MARKET",
      "message": "Market closed and transaction is between 2 different countries",
      "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch/v1/#errors",
      "details": []
    },
    "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/RWD4Y3H9VV8BA",
      "rel": "item",
      "method": "GET",
      "encType": "application/json"
    }]
  }],
  "links": [
  {
    "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/DQCP2UAJCBMNY",
    "rel": "self",
    "method": "GET",
    "encType": "application/json"
  }]
}

Test values

Use the listed test values to trigger positive and negative responses for these payouts actions:

• Create payout
• Show payout details
• Cancel payout item
• Show payout item details
• Batch processing

Note: Test values are case sensitive.

Create payout

Positive response test values

Use the JSON pointer method to simulate this response at POST v1/payments/payouts/.

Negative response test values

Use the JSON pointer method to simulate these error responses at POST v1/payments/payouts.

Show payout details

Positive response test values

Use the path parameter in the request URI method to simulate this response at GET v1/payments/payouts.

Negative response test values

Use the path parameter in the request URI method to simulate these error responses at GET v1/payments/payouts.

Cancel payout item

Positive response test values

Use the path parameter in the request URI method to simulate this response at POST v1/payments/payouts-item/payouts_item_id/cancel.

Negative response test values

Use the path parameter in the request URI method to simulate these error responses at POST v1/payments/payouts-item/payouts_item_id/cancel.

Show payout item details

Positive response test values

Use the path parameter in the request URI method to simulate this response at GET v1/payments/payouts-item/payouts_item_id.

Negative response test values

Use the path parameter in the request URI method to simulate these error responses at GET v1/payments/payouts-item/payouts_item_id.

Batch processing

Batch status test values

Use the path parameter in the request URI method to simulate these error responses at GET v1/payments/payouts/payout_batch_id.

Webhooks with failed payouts

Webhook resources don't contain error objects. If you receive a webhook for a failed payout and would like to understand why the payout failed, do a GET request on the object. For more details, see Webhook event names.

Rate limiting

The rate limit number for Payouts API POST calls is 400.

PayPal’s primary focus is site availability and security in support of merchants.

While we do not publish a rate limiting policy, we might temporarily rate limit if we identify traffic that appears to be abusive. We rate limit until we are confident that the activity is not problematic for PayPal, merchants, or customers.

To ensure maximum protection and site stability, we constantly evaluate traffic as it surges and subsides to adjust our policies. If you or your customers receive the HTTP 429 Unprocessable Entity - RATE_LIMIT_REACHED status code, too many requests were sent, and that might indicate anomalous traffic, so we rate limit to ensure site stability.

If this policy negatively affects your integration, contact Merchant Technical Support.

Tips to avoid rate limiting:

• Do not poll and instead use webhooks or IPN. To learn more, see Webhooks and Instant Payment Notification.

• Rather than generate an OAuth 2.0 access token for each transaction, cache tokens. See OAuth 2.0 authorization protocol.

Go live with your integration

Deploying your code to the live environment takes only a few steps.

1. Change the base URL for all your REST API calls from https://api-m.sandbox.paypal.com to https://api-m.paypal.com.

2. Change the references to your sandbox API credentials to the live credentials. To get live API credentials, create a live REST API.

   Tip: Remember to change the sandbox client ID in the JavaScript SDK call in your HTML.

3. If you created or updated pages on a website, move that code from the test environment to the live environment.

See also

• PayPal API Executor — Make test calls to the Payouts API.
• Payouts REST API