Skip to main content

Cancel unclaimed payout item

POST 
/payouts-item/:payout_item_id/cancel

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.

Request​

Path Parameters

    payout_item_id stringrequired

    Possible values: non-empty and <= 32 characters, Value must match regular expression ^.*$

    The ID of the payout item to cancel.

Responses​

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

Schema

    payout_item_id stringrequired

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

    Possible values: <= 30 characters, Value must match regular expression ^.*$

    transaction_id string

    The PayPal-generated ID for the transaction.

    Possible values: <= 30 characters, Value must match regular expression ^.*$

    activity_id string

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

    Possible values: <= 30 characters, Value must match regular expression ^.*$

    payout_batch_id stringrequired

    The PayPal-generated ID for the payout batch.

    Possible values: <= 30 characters, Value must match regular expression ^.*$

    sender_batch_id string

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

    Possible values: <= 256 characters, Value must match regular expression ^.*$

    time_processed date-time

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

    Possible values: non-empty and <= 100 characters

    links object[]

    An array of request-related HATEOAS links.

    Possible values: <= 15000

    transaction_status Transaction status (string)

    The item transaction status.

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

    Possible values: non-empty and <= 36 characters, Value must match regular expression ^[0-9A-Z_]+$, [SUCCESS, FAILED, PENDING, UNCLAIMED, RETURNED, ONHOLD, BLOCKED, REFUNDED, REVERSED]

    payout_item_fee

    object

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

    currency stringrequired
    value stringrequired

    The value, which might be:

    • An integer for currencies like JPY that are not typically fractional.
    • A decimal fraction for currencies like TND that are subdivided into thousandths.
    For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    payout_item

    object

    required

    The sender-provided information for the payout item.

    note string

    The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.

    Possible values: <= 4000 characters, Value must match regular expression ^.*$

    receiver stringrequired

    The receiver of the payment. Corresponds to the recipient_type value in the request.

    Possible values: <= 127 characters, Value must match regular expression ^.*$

    sender_item_id string

    A sender-specified ID number. Tracks the payout in an accounting system.

    Possible values: <= 63 characters, Value must match regular expression ^.*$

    recipient_type Recipient type (string)

    The ID type that identifies the payment receiver.

    Possible values: non-empty and <= 36 characters, Value must match regular expression ^[0-9A-Z_]+$, [EMAIL, PHONE, PAYPAL_ID]

    amount

    object

    required

    The currency and amount of payout item. Might be an integer for currencies like JPY that are not typically fractional or a decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    currency stringrequired
    value stringrequired

    The value, which might be:

    • An integer for currencies like JPY that are not typically fractional.
    • A decimal fraction for currencies like TND that are subdivided into thousandths.
    For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    recipient_name

    object

    The name of the recipient where money is credited. For UNCLAIMED payments, the recipient name is populated after the payment is claimed.

    prefix string

    The prefix, or title, to the party's name.

    Possible values: <= 140 characters

    given_name string

    When the party is a person, the party's given, or first, name.

    Possible values: <= 140 characters

    surname string

    When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.

    Possible values: <= 140 characters

    middle_name string

    When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.

    Possible values: <= 140 characters

    suffix string

    The suffix for the party's name.

    Possible values: <= 140 characters

    alternate_full_name string

    DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.

    Possible values: <= 300 characters

    full_name string

    When the party is a person, the party's full name.

    Possible values: <= 300 characters

    recipient_wallet Recipient wallet (string)

    The recipient wallet.

    Possible values: non-empty and <= 36 characters, Value must match regular expression ^[0-9A-Z_]+$, [PAYPAL, VENMO]

    Default value: PAYPAL
    purpose Purpose (string)

    The purpose of the transaction.

    Possible values: non-empty and <= 40 characters, Value must match regular expression ^[A-Z0-9_]+$, [AWARDS, PRIZES, DONATIONS, GOODS, SERVICES, REBATES, CASHBACK, DISCOUNTS, NON_GOODS_OR_SERVICES]

    currency_conversion

    object

    The currency conversion applicable for this payout item.

    exchange_rate string

    The exchange rate that is applied for this payout.

    Possible values: <= 30 characters, Value must match regular expression ^.*$

    from_amount

    object

    The currency and amount for a financial transaction, such as a balance or payment due.

    currency stringrequired
    value stringrequired

    The value, which might be:

    • An integer for currencies like JPY that are not typically fractional.
    • A decimal fraction for currencies like TND that are subdivided into thousandths.
    For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    to_amount

    object

    The currency and amount for a financial transaction, such as a balance or payment due.

    currency stringrequired
    value stringrequired

    The value, which might be:

    • An integer for currencies like JPY that are not typically fractional.
    • A decimal fraction for currencies like TND that are subdivided into thousandths.
    For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    errors

    object

    The error details.

    name stringrequired

    The human-readable, unique name of the error.

    message stringrequired

    The message that describes the error.

    debug_id stringrequired

    The PayPal internal ID. Used for correlation purposes.

    information_link string

    The information link, or URI, that shows detailed information about this error for the developer.

    details

    object[]

    An array of additional details about the error.

  • Array [

    • field string

    The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.

    value string

    The value of the field that caused the error.

    location string

    The location of the field that caused the error. Value is body, path, or query.

    Default value: body
    issue stringrequired

    The unique, fine-grained application-level error code.

    description string

    The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.

  • ]

    • links

    object[]

    An array of request-related HATEOAS links.

  • Array [

    • href stringrequired

    The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.

    rel stringrequired

    The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.

    method string

    The HTTP method required to make the related call.

    Possible values: [GET, POST, PUT, DELETE, HEAD, CONNECT, OPTIONS, PATCH]

  • ]

Loading...