Cancel unclaimed payout item

Cancels an unclaimed payout item, by ID. If no one claims the unclaimed item within 30 days, the API automatically returns the funds to the sender. Use this call to cancel the unclaimed item before the automatic 30-day refund. You can cancel payout items with a transaction_status of UNCLAIMED.

POST /v1/payments/payouts-item/{payout_item_id}/cancel

Cancel unclaimed payout item

cURL

curl --request POST \
  --url https://api-m.sandbox.paypal.com/v1/payments/payouts-item/{payout_item_id}/cancel \
  --header 'Authorization: Bearer <token>'

200

{
  "payout_item_id": "<string>",
  "payout_batch_id": "<string>",
  "payout_item": {
    "amount": {
      "currency": "<string>",
      "value": "<string>"
    },
    "receiver": "<string>",
    "recipient_type": "EMAIL",
    "note": "<string>",
    "sender_item_id": "<string>",
    "recipient_name": {
      "prefix": "<string>",
      "given_name": "<string>",
      "surname": "<string>",
      "middle_name": "<string>",
      "suffix": "<string>",
      "alternate_full_name": "<string>",
      "full_name": "<string>"
    },
    "recipient_wallet": "PAYPAL",
    "purpose": "AWARDS"
  },
  "transaction_id": "<string>",
  "activity_id": "<string>",
  "transaction_status": "SUCCESS",
  "payout_item_fee": {
    "currency": "<string>",
    "value": "<string>"
  },
  "sender_batch_id": "<string>",
  "currency_conversion": {
    "from_amount": {
      "currency": "<string>",
      "value": "<string>"
    },
    "to_amount": {
      "currency": "<string>",
      "value": "<string>"
    },
    "exchange_rate": "<string>"
  },
  "time_processed": "2023-11-07T05:31:56Z",
  "errors": {
    "name": "<string>",
    "message": "<string>",
    "debug_id": "<string>",
    "information_link": "<string>",
    "details": [
      {
        "issue": "<string>",
        "field": "<string>",
        "value": "<string>",
        "location": "body",
        "description": "<string>"
      }
    ],
    "links": [
      {
        "href": "<string>",
        "rel": "<string>",
        "method": "GET"
      }
    ]
  },
  "links": [
    {
      "href": "<string>",
      "rel": "<string>",
      "method": "GET"
    }
  ]
}

Authorizations

Authorization · string · header · required

Oauth 2.0 authentication

Path Parameters

payout_item_id · string · required

The ID of the payout item to cancel.

Required string length: 1 - 32

Pattern: ^.*$

Response

200

application/json

A successful request returns the HTTP 200 OK status code with a JSON response body that shows payout item details.

The payout item status and other details. A payout_item_id helps you identify denied payments. If a payment is denied, you can use the payout_item_id to identify the payment even if it lacks a transaction_id.

payout_item_id · string · required

The ID for the payout item. Visible when you show details for a payout.

Maximum string length: 30

Pattern: ^.*$

payout_batch_id · string · required

The PayPal-generated ID for the payout batch.

Maximum string length: 30

Pattern: ^.*$

payout_item · Payout Item Detail · object · required

The sender-provided information for the payout item.

Show child attributes

transaction_id · string

The PayPal-generated ID for the transaction.

Maximum string length: 30

Pattern: ^.*$

activity_id · string

The unique PayPal-generated common ID that links the sender- and receiver-side transactions. Used for tracking.

Maximum string length: 30

Pattern: ^.*$

transaction_status · enum<string>

The item transaction status.

Note: For POST/v1/payments/payouts-item/{payout_item_id}/cancel, the only possible transaction_status value is RETURNED.

Available options: SUCCESS, FAILED, PENDING, UNCLAIMED, RETURNED, ONHOLD, BLOCKED, REFUNDED, REVERSED

Required string length: 1 - 36

Pattern: ^[0-9A-Z_]+$

payout_item_fee · Currency · object

The estimate for the payout fee. Initially, the fee is 0. The fee is populated after the item moves to the PENDING state

Show child attributes

sender_batch_id · string

A sender-specified ID. Tracks the payout in an accounting system. Should be unique within 30 days.

Maximum string length: 256

Pattern: ^.*$

currency_conversion · Currency conversion resource · object

The currency conversion applicable for this payout item.

Show child attributes

time_processed · string<date-time>

The date and time when this item was last processed, in Internet date and time format.

Required string length: 1 - 100

errors · Error · object

The error details.

Show child attributes

links · Link Description · object[]

An array of request-related HATEOAS links.

Maximum array length: 15000

Show child attributes