Payments API

The date and time when the transaction occurred, in Internet date and time format.

The date and time when the transaction was last updated, in Internet date and time format.

The street number.

The street name. Just Drury in Drury Lane.

The street type. For example, avenue, boulevard, road, or expressway.

The delivery service. Post office box, bag number, or post office name.

A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.

The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.

The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.

The second line of the address. For example, suite or apartment number.

The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.

The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:

• The postal sorting code for Guernsey and many French territories, such as French Guiana.
• The fine-grained administrative levels in China.

A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:

• Brazil. Suburb, bairro, or neighborhood.
• India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.

A city, town, or village. Smaller than admin_area_level_1.

The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:

• UK. A county.
• US. A state.
• Canada. A province.
• Japan. A prefecture.
• Switzerland. A kanton.

The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.

The subtotal for all items. Required if the request includes purchase_units[].items[].unit_amount. Must equal the sum of (items[].unit_amount * items[].quantity) for all items.

The shipping fee for all items within a given purchase_unit.

The handling fee for all items within a given purchase_unit.

The total tax for all items. Required if the request includes purchase_units.items.tax. Must equal the sum of (items[].tax * items[].quantity) for all items.

The insurance fee for all items within a given purchase_unit.

The shipping discount for all items within a given purchase_unit.

The discount for all items within a given purchase_unit.

The status for the authorized payment.

The details of the authorized order pending status.

The PayPal-generated ID for the authorized payment.

The amount for this authorized payment.

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

The level of protection offered as defined by PayPal Seller Protection for Merchants.

The date and time when the authorized payment expires, in Internet date and time format.

An array of related HATEOAS links.

The date and time when the transaction occurred, in Internet date and time format.

The date and time when the transaction was last updated, in Internet date and time format.

The status for the authorized payment.

The possible values are:

• CREATED. The authorized payment is created. No captured payments have been made for this authorized payment.
• CAPTURED. The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.
• DENIED. PayPal cannot authorize funds for this authorized payment.
• EXPIRED. The authorized payment has expired.
• PARTIALLY_CAPTURED. A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.
• VOIDED. The authorized payment was voided. No more captured payments can be made against this authorized payment.
• PENDING. The created authorization is in pending state. For more information, see status.details

The details of the authorized order pending status.

The reason why the authorized status is PENDING.

The possible values are:

• PENDING_REVIEW. Authorization is pending manual review.

The status of the captured payment.

The details of the captured payment status.

The PayPal-generated ID for the captured payment.

The amount for this captured payment.

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

The level of protection offered as defined by PayPal Seller Protection for Merchants.

Indicates whether you can make additional captures against the authorized payment. Set to true if you do not intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.

The detailed breakdown of the captured payment.

The funds that are held on behalf of the merchant.

An array of related HATEOAS links.

The date and time when the transaction occurred, in Internet date and time format.

The date and time when the transaction was last updated, in Internet date and time format.

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.

The amount to capture. To capture a portion of the full authorized amount, specify an amount. If amount is not specified, the full authorized amount is captured. The amount must be a positive number and in the same currency as the authorization against which the payment is being captured.

Indicates whether you can make additional captures against the authorized payment. Set to true if you do not intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.

Any additional payment instructions for PayPal for Partner customers. Enables features for partners and marketplaces, such as delayed disbursement and collection of a platform fee. Applies during order creation for captured payments or during capture of authorized payments.

The status of the captured payment.

The possible values are:

• COMPLETED. The funds for this captured payment were credited to the payee's PayPal account.
• DECLINED. The funds could not be captured.
• PARTIALLY_REFUNDED. An amount less than this captured payment's amount was partially refunded to the payer.
• PENDING. The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details
• REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.

The details of the captured payment status.

The reason why the captured payment status is PENDING or DENIED.

The possible values are:

• BUYER_COMPLAINT. The payer initiated a dispute for this captured payment with PayPal.
• CHARGEBACK. The captured funds were reversed in response to the payer disputing this captured payment with the issuer of the financial instrument used to pay for this captured payment.
• ECHECK. The payer paid by an eCheck that has not yet cleared.
• INTERNATIONAL_WITHDRAWAL. Visit your online account. In your **Account Overview**, accept and deny this payment.
• OTHER. No additional specific reason can be provided. For more information about this captured payment, visit your account online or contact PayPal.
• PENDING_REVIEW. The captured payment is pending manual review.
• RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION. The payee has not yet set up appropriate receiving preferences for their account. For more information about how to accept or deny this payment, visit your account online. This reason is typically offered in scenarios such as when the currency of the captured payment is different from the primary holding currency of the payee.
• REFUNDED. The captured funds were refunded.
• TRANSACTION_APPROVED_AWAITING_FUNDING. The payer must send the funds for this captured payment. This code generally appears for manual EFTs.
• UNILATERAL. The payee does not have a PayPal account.
• VERIFICATION_REQUIRED. The payee's PayPal account is not verified.

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

The three-character ISO-4217 currency code that identifies the currency.

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

The funds that are held on behalf of the merchant.

The possible values are:

• INSTANT. The funds are released to the merchant immediately.
• DELAYED. The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.

The condition that is covered for the transaction.

The possible values are:

• ITEM_NOT_RECEIVED. The payer paid for an item that they did not receive.
• UNAUTHORIZED_TRANSACTION. The payer did not authorize the payment.

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

The human-readable, unique name of the error.

The message that describes the error.

The PayPal internal ID. Used for correlation purposes.

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

An array of additional details about the error.

An array of request-related HATEOAS links.

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.

The value of the field that caused the error.

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

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

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.

The source currency from which to convert an amount.

The target currency to which to convert an amount.

The target currency amount. Equivalent to one unit of the source currency. Formatted as integer or decimal value with one to 15 digits to the right of the decimal point.

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.

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

The HTTP method required to make the related call.

The three-character ISO-4217 currency code that identifies the currency.

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.

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

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

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.

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.

The suffix for the party's name.

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.

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

The net amount debited from the merchant's PayPal account.

The converted payable amount.

The exchange rate that determines the amount that was debited from the merchant's PayPal account.

The email address of merchant.

The encrypted PayPal account ID of the merchant.

The PayPal payer ID, which is a masked version of the PayPal account number intended for use with third parties. The account number is reversibly encrypted and a proprietary variant of Base32 is used to encode the result.

An array of various fees, commissions, tips, or donations.

The funds that are held on behalf of the merchant.

The possible values are:

• INSTANT. The funds are released to the merchant immediately.
• DELAYED. The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.

The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

The extension number.

The fee for this transaction.

The recipient of the fee for this transaction. If you omit this value, the default is the API caller.

The amount to reauthorize for an authorized payment.

The status of the capture.

The details of the refund status.

The PayPal-generated ID for the refund.

The amount that the payee refunded to the payer.

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.

The breakdown of the refund.

An array of related HATEOAS links.

The date and time when the transaction occurred, in Internet date and time format.

The date and time when the transaction was last updated, in Internet date and time format.

The amount to refund. To refund a portion of the captured amount, specify an amount. If amount is not specified, an amount equal to captured amount - previous refunds is refunded. The amount must be a positive number and in the same currency as the one in which the payment was captured.

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.

The status of the capture.

The possible values are:

• CANCELLED. The refund was cancelled.
• PENDING. The refund is pending. For more information, see status_details.reason.
• COMPLETED. The funds for this transaction were debited to the customer's account.

The details of the refund status.

The reason why the refund has the PENDING or FAILED status.

The possible values are:

• ECHECK. The customer's account is funded through an eCheck, which has not yet cleared.

The amount that the payee refunded to the payer.

The PayPal fee that was refunded to the payer. This fee might not match the PayPal fee that the payee paid when the payment was captured.

The net amount that the payee's account is debited, if the payee holds funds in the currency for this refund. The net amount is calculated as gross_amount minus paypal_fee minus platform_fees.

An array of platform or partner fees, commissions, or brokerage fees for the refund.

An array of breakdown values for the net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the payee holds their funds.

The total amount refunded from the original capture to date. For example, if a payer makes a $100 purchase and was refunded $20 a week ago and was refunded $30 in this refund, the gross_amount is $30 for this refund and the total_refunded_amount is $50.

Indicates whether the transaction is eligible for seller protection. For information, see PayPal Seller Protection for Merchants.

The possible values are:

• ELIGIBLE. Your PayPal balance remains intact if the customer claims that they did not receive an item or the account holder claims that they did not authorize the payment.
• PARTIALLY_ELIGIBLE. Your PayPal balance remains intact if the customer claims that they did not receive an item.
• NOT_ELIGIBLE. This transaction is not eligible for seller protection.

An array of conditions that are covered for the transaction.

The amount for this captured payment.

The applicable fee for this captured payment.

The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed as gross_amount minus the paypal_fee minus the platform_fees.

The net amount that is credited to the payee's PayPal account. Returned only when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds. The amount is computed as net_amount times exchange_rate.

The exchange rate that determines the amount that is credited to the payee's PayPal account. Returned when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds.

An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment.

The method by which the payer wants to get their items.

The possible values are:

• SHIPPING. The payer intends to receive the items at a specified address.
• PICKUP. The payer intends to pick up the items at a specified address. For example, a store address.

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.