Call the Payments API to authorize payments, capture authorized payments, refund payments that have already been captured, and show payment information. Use the Payments API in conjunction with the Orders API. For more information, see the PayPal Checkout Overview.
Shows details for an authorized payment, by ID.
Created
curl -v -X GET https://api-m.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer A21AAFs9YK9gWL6Vl6AqeoPtm-nf6JmtPOwAc8kfzHVdeigPEhrOJLCvbeIt3fJ4NKvyZo_iWic7sC3RIQrVUdu7igagcuMVQ'
{- "id": "0VF52814937998046",
- "status": "AUTHORIZED",
- "amount": {
- "total": "10.99",
- "currency": "USD"
}, - "invoice_id": "INVOICE-123",
- "seller_protection": {
- "status": "ELIGIBLE",
- "dispute_categories": [
- "ITEM_NOT_RECEIVED",
- "UNAUTHORIZED_TRANSACTION"
]
}, - "supplementary_data": {
- "related_ids": {
- "order_id": "29U15271MB9916641"
}
}, - "expiration_time": "2017-10-10T23:23:45Z",
- "create_time": "2017-09-11T23:23:45Z",
- "update_time": "2017-09-11T23:23:45Z",
- "links": [
- {
- "rel": "self",
- "method": "GET",
}, - {
- "rel": "capture",
- "method": "POST",
}, - {
- "rel": "void",
- "method": "POST",
}, - {
- "rel": "reauthorize",
- "method": "POST",
}
]
}
Captures an authorized payment, by ID.
A successful request returns the HTTP 201 Created
status code and a JSON response body that shows captured payment details.
{- "amount": {
- "value": "10.99",
- "currency_code": "USD"
}, - "invoice_id": "INVOICE-123",
- "final_capture": true,
- "note_to_payer": "If the ordered color is not available, we will substitute with a different color free of charge.",
- "soft_descriptor": "Bob's Custom Sweaters"
}
{- "id": "2GG279541U471931P",
- "status": "COMPLETED",
- "parent_transaction": {
- "id": "O-98V07748C3436772V",
- "type": "ORDER"
}, - "links": [
- {
- "rel": "self",
- "method": "GET",
}, - {
- "rel": "refund",
- "method": "POST",
}, - {
- "rel": "up",
- "method": "GET",
}
]
}
Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires.
If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment.
A reauthorized payment itself has a new honor period of three days.
You can reauthorize an authorized payment from 4 to 29 days after the 3-day honor period. The allowed amount depends on context and geography, for example in US it is up to 115% of the original authorized amount, not to exceed an increase of $75 USD.
Supports only the amount
request parameter.
Note: This request is currently not supported for Partner use cases.
object (Money) The amount to reauthorize for an authorized payment. |
A successful request returns the HTTP 201 Created
status code and a JSON response body that shows the reauthorized payment details.
{- "amount": {
- "value": "10.99",
- "currency_code": "USD"
}, - "invoice_id": "INVOICE-123",
- "payment_instruction": {
- "disbursement_mode": "INSTANT"
}, - "note_to_payer": "Payment For MAA Trip",
- "soft_descriptor": "AI*MAATrip",
- "supplementary_data": {
- "airline": [
- {
- "ticket": {
- "number": "045-2135145561",
- "issue_date": "2018-01-19",
- "issuing_carrier_code": "AI",
- "travel_agency_name": "World Tours",
- "travel_agency_code": "01"
}, - "passenger": {
- "name": {
- "full_name": "Trini George"
}, - "date_of_birth": "1981-05-31",
- "country_code": "US"
}, - "flight_leg_details": [
- {
- "flight_number": 101,
- "carrier_code": "AI",
- "service_class": "J",
- "departure_date": "2018-02-15",
- "departure_time": "15:30",
- "departure_airport": "SFO",
- "arrival_airport": "DBX",
- "stopover_code": "X",
- "fare_basis_code": "SPRSVR"
}, - {
- "flight_number": 102,
- "carrier_code": "AI",
- "service_class": "J",
- "departure_date": "2018-02-15",
- "departure_time": "19:05",
- "departure_airport": "DBX",
- "arrival_airport": "MAA",
- "stopover_code": "O",
- "fare_basis_code": "SPRSVR"
}
]
}
]
}
}
{- "id": "8AA831015G517922L",
- "status": "CREATED",
- "links": [
- {
- "rel": "self",
- "method": "GET",
}, - {
- "rel": "capture",
- "method": "POST",
}, - {
- "rel": "void",
- "method": "POST",
}, - {
- "rel": "reauthorize",
- "method": "POST",
}
]
}
Voids, or cancels, an authorized payment, by ID. You cannot void an authorized payment that has been fully captured.
Authorization required | string To make REST API calls, include the bearer token in the |
Content-Type required | string Required for operations with a request body. The value is application/ |
PayPal-Auth-Assertion | string An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion. Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject. |
Prefer | string Default: return=minimal The preferred server response upon successful completion of the request. Value is:
|
A successful request returns the HTTP 204 No Content
status code with no JSON response body. This response is returned when the Prefer header is set to return=minimal.
curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046/void \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer A21AAFs9YK9gWL6Vl6AqeoPtm-nf6JmtPOwAc8kfzHVdeigPEhrOJLCvbeIt3fJ4NKvyZo_iWic7sC3RIQrVUdu7igagcuMVQ'
Shows details for a captured payment, by ID.
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows captured payment details.
curl -v -X GET https://api-m.sandbox.paypal.com/v2/payments/captures/2GG279541U471931P \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer A21AAFs9YK9gWL6Vl6AqeoPtm-nf6JmtPOwAc8kfzHVdeigPEhrOJLCvbeIt3fJ4NKvyZo_iWic7sC3RIQrVUdu7igagcuMVQ'
{- "id": "2GG279541U471931P",
- "status": "COMPLETED",
- "status_details": { },
- "amount": {
- "total": "10.99",
- "currency": "USD"
}, - "final_capture": true,
- "seller_protection": {
- "status": "ELIGIBLE",
- "dispute_categories": [
- "ITEM_NOT_RECEIVED",
- "UNAUTHORIZED_TRANSACTION"
]
}, - "seller_receivable_breakdown": {
- "gross_amount": {
- "total": "10.99",
- "currency": "USD"
}, - "paypal_fee": {
- "value": "0.33",
- "currency": "USD"
}, - "net_amount": {
- "value": "10.66",
- "currency": "USD"
}, - "receivable_amount": {
- "currency_code": "CNY",
- "value": "59.26"
}, - "paypal_fee_in_receivable_currency": {
- "currency_code": "CNY",
- "value": "1.13"
}, - "exchange_rate": {
- "source_currency": "USD",
- "target_currency": "CNY",
- "value": "5.9483297432325"
}
}, - "invoice_id": "INVOICE-123",
- "create_time": "2017-09-11T23:24:01Z",
- "update_time": "2017-09-11T23:24:01Z",
- "links": [
- {
- "rel": "self",
- "method": "GET"
}, - {
- "rel": "refund",
- "method": "POST"
}, - {
- "rel": "up",
- "method": "GET"
}
]
}
Refunds a captured payment, by ID. For a full refund, include an empty payload in the JSON request body. For a partial refund, include an amount
object in the JSON request body.
PayPal-Request-Id | string The server stores keys for 45 days. |
Prefer | string Default: return=minimal The preferred server response upon successful completion of the request. Value is:
|
Authorization required | string To make REST API calls, include the bearer token in the |
Content-Type required | string Required for operations with a request body. The value is application/ |
PayPal-Auth-Assertion | string An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion. Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject. |
A successful request returns the HTTP 201 Created
status code and a JSON response body that shows refund details.
{- "amount": {
- "value": "10.00",
- "currency_code": "USD"
}, - "invoice_id": "INVOICE-123",
- "note_to_payer": "DefectiveProduct",
- "payment_instruction": {
- "platform_fees": [
- {
- "amount": {
- "currency_code": "USD",
- "value": "1.00"
}
}
]
}
}
{- "id": "1JU08902781691411",
- "amount": {
- "value": "10.00",
- "currency_code": "USD"
}, - "status": "COMPLETED",
- "note": "Defective product",
- "seller_payable_breakdown": {
- "gross_amount": {
- "value": "10.00",
- "currency_code": "USD"
}, - "paypal_fee": {
- "value": "0",
- "currency_code": "USD"
}, - "platform_fees": [
- {
- "amount": {
- "currency_code": "USD",
- "value": "1.00"
}
}
], - "net_amount": {
- "value": "9.00",
- "currency_code": "USD"
}, - "total_refunded_amount": {
- "value": "10.00",
- "currency_code": "USD"
}
}, - "invoice_id": "INVOICE-123",
- "create_time": "2022-04-23T23:24:19Z",
- "update_time": "2022-04-23T23:24:19Z",
- "links": [
- {
- "rel": "self",
- "method": "GET",
}, - {
- "rel": "up",
- "method": "GET",
}
]
}
Shows details for a refund, by ID.
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows refund details.
curl -v -X GET https://api-m.sandbox.paypal.com/v2/payments/refunds/1JU08902781691411 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer A21AAFs9YK9gWL6Vl6AqeoPtm-nf6JmtPOwAc8kfzHVdeigPEhrOJLCvbeIt3fJ4NKvyZo_iWic7sC3RIQrVUdu7igagcuMVQ'
{- "id": "1JU08902781691411",
- "amount": {
- "value": "10.99",
- "currency_code": "USD"
}, - "status": "COMPLETED",
- "note": "Defective product",
- "seller_payable_breakdown": {
- "gross_amount": {
- "value": "10.99",
- "currency_code": "USD"
}, - "paypal_fee": {
- "value": "0.33",
- "currency_code": "USD"
}, - "platform_fees": [
- {
- "amount": {
- "currency_code": "USD",
- "value": "1.00"
}, - "payee": {
- "email_address": "fee@example.com"
}
}
], - "net_amount": {
- "value": "9.66",
- "currency_code": "USD"
}, - "total_refunded_amount": {
- "value": "10.99",
- "currency_code": "USD"
}
}, - "invoice_id": "INVOICE-123",
- "create_time": "2018-09-11T23:24:19Z",
- "update_time": "2018-09-11T23:24:19Z",
- "links": [
- {
- "rel": "self",
- "method": "GET",
}, - {
- "rel": "up",
- "method": "GET",
}
]
}
Message:
Currency of capture must be the same as currency of authorization.
Description:
Verify the currency of the capture and try the request again.
Message:
The currency specified during reauthorization should be the same as the currency specified in the original authorization. Please check the currency of the authorization for which you are trying to reauthorize and try again.
Message:
Authentication failed due to missing authorization header, or invalid authentication credentials.
Description:
Account validations failed for the user.
Message:
Authorization has already been captured.
Description:
If final_capture
is set to to true
, additional captures are not possible against the authorization.
Description: Authorization amount specified exceeded allowable limit. Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits. Local regulations (e.g. in PSD2 countries) prohibit overages above the amount authorized by the payer.
Message:
A denied authorization cannot be captured.
Description:
You cannot capture a denied authorization.
Message:
An expired authorization cannot be captured.
Description:
You cannot capture an expired authorization.
Message:
A voided authorization cannot be captured or reauthorized.
Description:
You cannot capture or reauthorize a voided authorization.
Message:
A reauthorization cannot be voided. Please void the original parent authorization.
Description:
You cannot void a reauthorized payment. You must void the original parent authorized payment.
Message:
Must be greater than zero. If the currency supports decimals, only two decimal place precision is supported.
Description:
Specify a different value and try the request again.
Message:
The capture has already been fully refunded.
Description:
You cannot capture additional refunds against this capture.
Description: Specified country is not currently supported for payment processing.
Description: Refund cannot be issued to this card. The card brand card_brand
is not supported. Please try again with another card.
Description: Card is issued by a financial institution for a country (e.g. Cuba, Iran, North Korea, Syria) that is not current supported for payment processing.
Description: Processing of this card type is not supported. Use another type of card.
Message:
All amounts specified should be in the same currency. Please ensure that the currency for the 'amount' and that of 'platform_fees.amount' is the same.
Description: Currency not supported for card specified. Card is card_brand
. Only currency_code
is supported for this brand of card.
Description: Currency code not supported for direct card payments using this card type. See Currency codes for list of supported currency codes.
Description: Currency code not supported for card payments in your country.
Message:
The value of the field should not be more than two decimal places.
Description:
If the currency supports decimals, only two decimal place precision is supported.
Message:
Currency does not support decimals.
Description:
Currency does not support decimals. Please refer to https://developer.paypal.com/docs/api/reference/currency-codes/ for more information.
Message:
The API Caller is not enabled to process transactions by specifying disbursement mode as delayed.
Description:
Verify the API caller is enabled to process transaction with delayed disbursement.
Message:
Requested invoice number has been previously captured. Possible duplicate transaction.
Description:
Payment for this invoice was already captured.
Description: Requested invoice_id has been previously refunded. Possible duplicate transaction.
Description: The FX rate associated with the specified FX rate ID has been changed due to market events. Please refer to the provided new_fx_id link to retrieve a new FX rate ID and try the request again.
Description: The instrument presented was either declined by the processor or bank, or it can't be used for this payment.
Message:
An internal server error has occurred.
Description:
Try your request again later.
Message:
Account validations failed for the user.
Description:
The user account could not be validated.
Message:
Request is not well-formed, syntactically incorrect, or violates schema.
Description:
The number of items in an array parameter is too small or too large.
Message:
The requested action could not be performed, semantically incorrect, or failed business validation.
Description:
Country code is invalid. Please refer to https://developer.paypal.com/docs/integration/direct/rest/country-codes/ for a list of supported country codes.
Message:
Currency code should be a three-character ISO-4217 currency code.
Description:
Currency code is invalid or is not currently supported. Please refer https://developer.paypal.com/docs/api/reference/currency-codes/ for list of supported currency codes.
Message:
Specified invoice_id does not exist.
Description:
Please check the invoice_id and try again.
Message:
The value of the field does not conform to the expected format.
Description:
Verify the specification for supported pattern
and try the request again.
Message:
The value of a field is invalid.
Description:
Verify the specification for the allowed values and try the request again.
Message:
Payee account is invalid.
Description:
Verify the payee account information and try the request again.
Message:
The specified platform_fees payee account is either invalid or account setup is incomplete. Please work with your PayPal Account Manager to enable this option for your account.
Description:
Verify the platform fee account set up is completed or correct account.
Message:
The platform_fees
amount cannot be greater than the capture amount.
Description:
Verify the platform_fees
amount and try the request again.
Message:
Specified resource ID does not exist. Please check the resource ID and try again.
Description:
Verify the resource ID and try the request again.
Description: The security_code length is invalid for the specified card brand.
Message:
The value of a field is either too short or too long.
Description:
Verify the specification for the supported min
and max
values and try the request again.
Message:
The value of a field is too long.
Description:
The parameter string is too long.
Message:
Request is not well-formed, syntactically incorrect, or violates schema.
Description: The request JSON is not well formed.
Message:
Capture amount exceeds allowable limit. Please contact customer service or your account manager to request the change to your overage limit. The default overage limit is 115%, which allows the sum of all captures to be up to 115% of the order amount. Local regulations (e.g. in PSD2 countries) prohibit overages above the amount authorized by the payer.
Description:
Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits.
Message:
Maximum number of allowable captures has been reached. No additional captures are possible for this authorization. Please contact customer service or your account manager to change the number of captures that be made for a given authorization.
Description:
You cannot make additional captures.
Message:
You have exceeded the number of refunds that can be processed per capture.
Description:
Please contact customer support or your account manager to review the number of refunds that can be processed per capture.
Description: Refund amount exceeds the allowed cumulative limit that the payee can receive.
Description: Refund amount exceeds the allowed cumulative limit that the payer can refund.
Description: Refund amount exceeds allowable limit. Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits.
Message:
A required field / parameter is missing.
Description:
Verify the specification for required
fields and try the request again.
Message:
The requested action could not be performed, semantically incorrect, or failed business validation.
Description:
Multiple differing values of currency_code are not supported. Entire request must have the same currency_code.
Message:
Cannot void multiple authorizations.
Description:
Specified invoice_id is associated with more than one authorization.
Message:
You do not have permission to access or perform operations on this resource.
Description:
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction.
Message:
You cannot do a refund for an amount less than the original capture amount.
Description:
Specify an amount equal to the capture amount or omit the amount
object from the request. Then, try the request again.
Message:
The requested action could not be performed, semantically incorrect, or failed business validation.
Description:
Payee account specified is invalid. Please check the payee.merchant_id
specified and try again.
Message:
Transaction could not complete because payee account is locked or closed.
Description:
To get more information about the status of the account, call Customer Support.
Message:
Payee account is restricted.
Description:
To get more information about the status of the account, call Customer Support.
Description: The specified FX Rate ID is for a currency that does not match with the currency of this request.
Description: Payee does not have appropriate consent to allow the API caller to process this type of transaction on their behalf. Your current setup requires the 'payee' to provide a consent before this transaction can be processed successfully.
Description: Refund amount exceeds per transaction limit that the payee can receive.
Message:
The payer account cannot be used for this transaction.
Description:
Contact the payer for an alternate payment method.
Message:
Payer account is restricted.
Description:
To get more information about the status of the account, call Customer Support.
Message:
Payer cannot pay for this transaction.
Description:
Please contact the payer to find other ways to pay for this transaction.
Description: Refund amount exceeds per transaction limit that the payer can refund.
Message:
Cannot initiate a refund as the capture is pending.
Description:
Capture is typically pending when the payer has funded the transaction by using an e-check or bank account.
Message:
You do not have permission to access or perform operations on this resource.
Description:
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction.
Message:
Payee of the authorization has not granted permission to perform capture on the authorization.
Description:
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to capture the authorization.
Message:
Platform fee amount specified exceeds the amount that is available for refund. You can only refund up to the available platform fee amount. This error is also returned when no platform_fee was specified or was zero when the payment was captured.
Message:
The API Caller account is not setup to be able to process refunds with 'platform_fees'. Please contact your Account Manager. This feature is useful when you want to contribute a portion of the 'platform_fees' you had capture as part of the refund being processed.
Message:
The API Caller is not enabled to process transactions by specifying 'platform_fees'. Please work with your PayPal Account Manager to enable this option for your account.
Description:
Verify the API caller is enabled to process the transaction with platform fees.
Message:
A previous request on this resource is currently in progress. Please wait for sometime and try again. It is best to space out the initial and the subsequent request(s) to avoid receiving this error.
Description:
This scenario only occurs when making multiple API requests on the same resource within a very short duration. To resolve this, API callers need to make subsequent requests with a delay.
Message:
Authorization has been previously captured and hence cannot be voided.
Description:
This authorized payment was already captured. You cannot capture it again.
Message:
Authorization has been previously voided and hence cannot be voided again.
Description:
This authorized payment was already voided. You cannot void it again.
Message:
Too many requests. Blocked due to rate limiting.
Description: The rate limit was reached.
Message:
A reauthorize cannot be attempted on an authorization_id that is the result of a prior reauthorization or on an authorization made on an Order saved using the v2/orders/id/save
API.
Description: A reauthorization is only allowed once from Day 4 to Day 29 since the date of the original authorization.
Message:
The refund amount must be less than or equal to the capture amount that has not yet been refunded.
Description:
Verify the refund amount and try the request again.
Message:
The amount after applying currency conversion is zero and hence the capture cannot be refunded. The currency conversion is required because the currency of the capture is different than the currency in which the amount was settled into the payee account.
Description:
The amount after applying currency conversion is zero and hence the capture cannot be refunded. The currency conversion is required because the currency of the capture is different than the currency in which the amount was settled into the payee account.
Message:
Refund must be in the same currency as the capture.
Description:
Verify the currency of the refund and try the request again.
Message:
Refund was refused by the payment source.
Description:
We're unable to process refunds for the payer's selected payment source. Contact the payer directly to arrange a refund via alternative means.
Message:
Refund cannot be processed due to insufficient funds.
Description:
Capture could not be refunded due to insufficient funds. Please check to see if you have sufficient funds in your PayPal account or if the bank account linked to your PayPal account is verified and has sufficient funds.
Description: There is no valid funding instrument linked to the account from which refund can be processed.
Message:
This refund can only be processed by the API caller that had 'captured' the transaction. If you facilitate your transactions via a platform/partner, please initiate a refund through them.
Message:
The requested action could not be performed, semantically incorrect, or failed business validation.
Description:
Refunds not allowed on this capture due to a chargeback on the card or bank. Please contact the payee to resolve the chargeback.
Message:
Refund was refused by the payment source.
Description:
Refunds are not supported for the payer's selected payment source. Contact the payer directly to arrange a refund via alternative means.
Description: The funding instrument linked to the account has been declined by either the processor or PayPal internal system.
Message:
Refund was refused by the payment source.
Description:
The time limit set by the payer's selected payment source to refund this transaction has expired. Contact the payer directly to arrange a refund via alternative means.
Message:
You are over the time limit to perform a refund on this capture.
Description:
The refund cannot be issued at this time.
Description: PayPal's internal controls or user account settings prevent refund from being processed.
Message:
The provided shipping address is not allowed by buyer's residency country.
Message:
Partial refunds cannot be offered at this time because there is an open case on this transaction. Visit the PayPal Resolution Center to review this case.
Description:
Refund for an amount less than the remaining transaction amount cannot be processed at this time because of an open dispute on the capture. Please visit the PayPal Resolution Center to view the details.
Message:
PayPal's internal controls prevent authorization from being captured.
Description:
For more information about this transaction, contact customer support.
Message:
Update authorization is not allowed for this type of authorization.
Card brand that the transaction was processed for authentication.
Card brand that the transaction was processed for authentication.
Enum: | Description |
---|---|
AMERICAN_EXPRESS | Card Brand Amex. |
DISCOVER | Card Brand DISCOVER. |
JCB | Card Brand JCB. |
MAESTRO | Card Brand MAESTRO. |
MASTERCARD | Card Brand MASTERCARD. |
SOLO | Card Brand SOLO. |
VISA | Card Brand VISA. |
ELECTRON | Card Brand ELECTRON. |
ELO | Card Brand ELO. |
"AMERICAN_EXPRESS"
The date and time stamps that are common to authorized payment, captured payment, and refund transactions.
create_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction occurred, in Internet date and time format. |
update_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction was last updated, in Internet date and time format. |
{- "create_time": "stringstringstringst",
- "update_time": "stringstringstringst"
}
The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
object (Money) The subtotal for all items. Required if the request includes | |
object (Money) The shipping fee for all items within a given | |
object (Money) The handling fee for all items within a given | |
object (Money) The total tax for all items. Required if the request includes | |
object (Money) The insurance fee for all items within a given | |
object (Money) The shipping discount for all items within a given | |
object (Money) The discount for all items within a given |
{- "item_total": {
- "currency_code": "str",
- "value": "string"
}, - "shipping": {
- "currency_code": "str",
- "value": "string"
}, - "handling": {
- "currency_code": "str",
- "value": "string"
}, - "tax_total": {
- "currency_code": "str",
- "value": "string"
}, - "insurance": {
- "currency_code": "str",
- "value": "string"
}, - "shipping_discount": {
- "currency_code": "str",
- "value": "string"
}, - "discount": {
- "currency_code": "str",
- "value": "string"
}
}
The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown
, the amount equals item_total
plus tax_total
plus shipping
plus handling
plus insurance
minus shipping_discount
minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.
currency_code required | string <ppaas_common_currency_code_v2> (currency_code) = 3 characters The three-character ISO-4217 currency code that identifies the currency. |
value required | string <= 32 characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ The value, which might be:
|
object (amount_breakdown) The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any. |
{- "currency_code": "str",
- "value": "string",
- "breakdown": {
- "item_total": {
- "currency_code": "str",
- "value": "string"
}, - "shipping": {
- "currency_code": "str",
- "value": "string"
}, - "handling": {
- "currency_code": "str",
- "value": "string"
}, - "tax_total": {
- "currency_code": "str",
- "value": "string"
}, - "insurance": {
- "currency_code": "str",
- "value": "string"
}, - "shipping_discount": {
- "currency_code": "str",
- "value": "string"
}, - "discount": {
- "currency_code": "str",
- "value": "string"
}
}
}
Additional attributes associated with apple pay.
object (customer) The details about a customer in PayPal's system of record. | |
object (v3_vault_instruction_base) Base vaulting specification. The object can be extended for specific use cases within each payment_source that supports vaulting. |
{- "customer": {
- "id": "string",
- "email_address": "string",
- "phone": {
- "phone_type": "FAX",
- "phone_number": {
- "national_number": "string"
}
}
}, - "vault": {
- "store_in_vault": "ON_SUCCESS"
}
}
Information about the Payment data obtained by decrypting Apple Pay token.
device_manufacturer_id | string [ 1 .. 2000 ] characters ^.*$ Apple Pay Hex-encoded device manufacturer identifier. The pattern is defined by an external party and supports Unicode. | ||||||
payment_data_type | string [ 1 .. 16 ] characters ^[0-9A-Z_]+$ Indicates the type of payment data passed, in case of Non China the payment data is 3DSECURE and for China it is EMV.
| ||||||
object (Money) The transaction amount for the payment that the payer has approved on apple platform. | |||||||
required | object (card) Apple Pay tokenized credit card used to pay. | ||||||
object (apple_pay_payment_data) Apple Pay payment data object which contains the cryptogram, eci_indicator and other data. |
{- "device_manufacturer_id": "string",
- "payment_data_type": "3DSECURE",
- "transaction_amount": {
- "currency_code": "str",
- "value": "string"
}, - "tokenized_card": {
- "name": "string",
- "number": "stringstrings",
- "expiry": "string",
- "card_type": "VISA",
- "type": "CREDIT",
- "brand": "VISA",
- "billing_address": {
- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
}, - "payment_data": {
- "cryptogram": "string",
- "eci_indicator": "string",
- "emv_data": "string",
- "pin": "string"
}
}
Information about the decrypted apple pay payment data for the token like cryptogram, eci indicator.
cryptogram | string [ 1 .. 2000 ] characters ^.*$ Online payment cryptogram, as defined by 3D Secure. The pattern is defined by an external party and supports Unicode. |
eci_indicator | string [ 1 .. 256 ] characters ^.*$ ECI indicator, as defined by 3- Secure. The pattern is defined by an external party and supports Unicode. |
emv_data | string [ 1 .. 2000 ] characters ^.*$ Encoded Apple Pay EMV Payment Structure used for payments in China. The pattern is defined by an external party and supports Unicode. |
pin | string [ 1 .. 2000 ] characters ^.*$ Bank Key encrypted Apple Pay PIN. The pattern is defined by an external party and supports Unicode. |
{- "cryptogram": "string",
- "eci_indicator": "string",
- "emv_data": "string",
- "pin": "string"
}
Information about cardholder possession validation and cardholder identification and verifications (ID&V).
account_verified | boolean Default: false If true, indicates that Cardholder possession validation has been performed on returned payment credential. |
card_holder_authenticated | boolean Default: false If true, indicates that identification and verifications (ID&V) was performed on the returned payment credential.If false, the same risk-based authentication can be performed as you would for card transactions. This risk-based authentication can include, but not limited to, step-up with 3D Secure protocol if applicable. |
{- "account_verified": false,
- "card_holder_authenticated": false
}
Results of Authentication such as 3D Secure.
liability_shift | string (liability_shift) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Liability shift indicator. The outcome of the issuer's authentication.
| ||||||||
object (three_d_secure_authentication_response) Results of 3D Secure Authentication. |
{- "liability_shift": "NO",
- "three_d_secure": {
- "authentication_status": "Y",
- "enrollment_status": "Y"
}
}
Indicates the type of authentication that was used to challenge the card holder.
Indicates the type of authentication that was used to challenge the card holder.
Enum: | Description |
---|---|
STATIC | Indicates fixed password. |
DYNAMIC | Indicates one-time password. Could be single-step or multi-step. |
OUT_OF_BAND | Indicates biometric over the phone. |
DECOUPLED | Indicates decoupled authentication. |
"STATIC"
The authorized payment transaction.
status | string (Authorization Status) The status for the authorized payment.
| ||||||||||||||
object (authorization_status_details) The details of the authorized order pending status. | |||||||||||||||
id | string The PayPal-generated ID for the authorized payment. | ||||||||||||||
invoice_id | string 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. | ||||||||||||||
custom_id | string <= 255 characters The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. | ||||||||||||||
Array of objects (Link Description) An array of related HATEOAS links. | |||||||||||||||
object (Money) The amount for this authorized payment. | |||||||||||||||
object (network_transaction_reference) Reference values used by the card network to identify a transaction. | |||||||||||||||
object (seller_protection) The level of protection offered as defined by PayPal Seller Protection for Merchants. | |||||||||||||||
expiration_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the authorized payment expires, in Internet date and time format. | ||||||||||||||
create_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction occurred, in Internet date and time format. | ||||||||||||||
update_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction was last updated, in Internet date and time format. |
{- "status": "CREATED",
- "status_details": {
- "reason": "PENDING_REVIEW"
}, - "id": "string",
- "invoice_id": "string",
- "custom_id": "string",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "amount": {
- "currency_code": "str",
- "value": "string"
}, - "network_transaction_reference": {
- "id": "stringstr",
- "date": "stri",
- "acquirer_reference_number": "string",
- "network": "VISA"
}, - "seller_protection": {
- "status": "ELIGIBLE",
- "dispute_categories": [
- "string"
]
}, - "expiration_time": "string",
- "create_time": "stringstringstringst",
- "update_time": "stringstringstringst"
}
The authorized payment transaction.
status | string (Authorization Status) The status for the authorized payment.
| ||||||||||||||
object (authorization_status_details) The details of the authorized order pending status. | |||||||||||||||
id | string The PayPal-generated ID for the authorized payment. | ||||||||||||||
invoice_id | string 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. | ||||||||||||||
custom_id | string <= 255 characters The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. | ||||||||||||||
Array of objects (Link Description) An array of related HATEOAS links. | |||||||||||||||
object (Money) The amount for this authorized payment. | |||||||||||||||
object (network_transaction_reference) Reference values used by the card network to identify a transaction. | |||||||||||||||
object (seller_protection) The level of protection offered as defined by PayPal Seller Protection for Merchants. | |||||||||||||||
expiration_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the authorized payment expires, in Internet date and time format. | ||||||||||||||
create_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction occurred, in Internet date and time format. | ||||||||||||||
update_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction was last updated, in Internet date and time format. | ||||||||||||||
object (Payment Supplementary Data) An object that provides supplementary/additional data related to a payment transaction. | |||||||||||||||
object (payee_base) The details associated with the merchant for this transaction. |
{- "status": "CREATED",
- "status_details": {
- "reason": "PENDING_REVIEW"
}, - "id": "string",
- "invoice_id": "string",
- "custom_id": "string",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "amount": {
- "currency_code": "str",
- "value": "string"
}, - "network_transaction_reference": {
- "id": "stringstr",
- "date": "stri",
- "acquirer_reference_number": "string",
- "network": "VISA"
}, - "seller_protection": {
- "status": "ELIGIBLE",
- "dispute_categories": [
- "string"
]
}, - "expiration_time": "string",
- "create_time": "stringstringstringst",
- "update_time": "stringstringstringst",
- "supplementary_data": {
- "related_ids": {
- "order_id": "string",
- "authorization_id": "string",
- "capture_id": "string"
}
}, - "payee": {
- "email_address": "string",
- "merchant_id": "stringstrings"
}
}
The status fields and status details for an authorized payment.
status | string (Authorization Status) The status for the authorized payment.
| ||||||||||||||
object (authorization_status_details) The details of the authorized order pending status. |
{- "status": "CREATED",
- "status_details": {
- "reason": "PENDING_REVIEW"
}
}
The details of the authorized payment status.
reason | string (Authorization Incomplete Reason) [ 1 .. 64 ] characters ^[A-Z_]+$ The reason why the authorized status is
|
{- "reason": "PENDING_REVIEW"
}
The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.
The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.
"stringst"
The PayPal billing agreement ID. References an approved recurring payment for goods or services.
The PayPal billing agreement ID. References an approved recurring payment for goods or services.
"string"
Bank Identification Number (BIN) details used to fund a payment.
bin | string [ 1 .. 25 ] characters ^[0-9]+$ The Bank Identification Number (BIN) signifies the number that is being used to identify the granular level details (except the PII information) of the card. |
issuing_bank | string [ 1 .. 64 ] characters The issuer of the card instrument. |
products | Array of strings [ 1 .. 256 ] items The type of card product assigned to the BIN by the issuer. These values are defined by the issuer and may change over time. Some examples include: PREPAID_GIFT, CONSUMER, CORPORATE. |
bin_country_code | string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$ The two-character ISO-3166-1 country code of the bank. |
{- "bin": "string",
- "issuing_bank": "string",
- "products": [
- "string"
], - "bin_country_code": "string"
}
Customizes the payer experience during the approval process for the BLIK payment.
brand_name | string [ 1 .. 127 ] characters ^.*$ The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode. | ||||||||
shipping_preference | string [ 1 .. 24 ] characters ^[A-Z_]+$ Default: "GET_FROM_FILE" The location from which the shipping address is derived.
| ||||||||
locale | string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[... The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, | ||||||||
return_url | string <uri> (url) The URL where the customer is redirected after the customer approves the payment. | ||||||||
cancel_url | string <uri> (url) The URL where the customer is redirected after the customer cancels the payment. | ||||||||
consumer_user_agent | string [ 1 .. 256 ] characters ^.*$ The payer's User Agent. For example, Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0). | ||||||||
consumer_ip | string <ppaas_ip_address_v1> (IP Address) [ 7 .. 39 ] characters ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[... The IP address of the consumer. It could be either IPv4 or IPv6. |
{- "brand_name": "string",
- "shipping_preference": "GET_FROM_FILE",
- "locale": "string",
- "return_url": "string",
- "cancel_url": "string",
- "consumer_user_agent": "string",
- "consumer_ip": "string"
}
Information used to pay using BLIK level_0 flow.
auth_code required | string = 6 characters ^[0-9]{6}$ The 6-digit code used to authenticate a consumer within BLIK. |
{- "auth_code": "string"
}
Information used to pay using BLIK one-click flow.
auth_code | string = 6 characters ^[0-9]{6}$ The 6-digit code used to authenticate a consumer within BLIK. |
consumer_reference required | string [ 3 .. 64 ] characters ^[ -~]{3,64}$ The merchant generated, unique reference serving as a primary identifier for accounts connected between Blik and a merchant. |
alias_label | string [ 8 .. 35 ] characters ^[ -~]{8,35}$ A bank defined identifier used as a display name to allow the payer to differentiate between multiple registered bank accounts. |
alias_key | string [ 1 .. 19 ] characters ^[0-9]+$ A Blik-defined identifier for a specific Blik-enabled bank account that is associated with a given merchant. Used only in conjunction with a Consumer Reference. |
{- "auth_code": "string",
- "consumer_reference": "string",
- "alias_label": "stringst",
- "alias_key": "string"
}
A captured payment.
status | string (Capture Status) The status of the captured payment.
| ||||||||||||||
object (capture_status_details) The details of the captured payment status. | |||||||||||||||
id | string The PayPal-generated ID for the captured payment. | ||||||||||||||
invoice_id | string 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. | ||||||||||||||
custom_id | string <= 255 characters The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. | ||||||||||||||
final_capture | boolean Default: false Indicates whether you can make additional captures against the authorized payment. Set to | ||||||||||||||
disbursement_mode | string (disbursement_mode) [ 1 .. 16 ] characters ^[A-Z_]+$ Default: "INSTANT" The funds that are held on behalf of the merchant.
| ||||||||||||||
Array of objects (Link Description) An array of related HATEOAS links. | |||||||||||||||
object (Money) The amount for this captured payment. | |||||||||||||||
object (network_transaction_reference) Reference values used by the card network to identify a transaction. | |||||||||||||||
object (seller_protection) The level of protection offered as defined by PayPal Seller Protection for Merchants. | |||||||||||||||
object (Seller Receivable Breakdown) The detailed breakdown of the capture activity. This is not available for transactions that are in pending state. | |||||||||||||||
object (processor_response) An object that provides additional processor information for a direct credit card transaction. | |||||||||||||||
create_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction occurred, in Internet date and time format. | ||||||||||||||
update_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction was last updated, in Internet date and time format. |
{- "status": "COMPLETED",
- "status_details": {
- "reason": "BUYER_COMPLAINT"
}, - "id": "string",
- "invoice_id": "string",
- "custom_id": "string",
- "final_capture": false,
- "disbursement_mode": "INSTANT",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "amount": {
- "currency_code": "str",
- "value": "string"
}, - "network_transaction_reference": {
- "id": "stringstr",
- "date": "stri",
- "acquirer_reference_number": "string",
- "network": "VISA"
}, - "seller_protection": {
- "status": "ELIGIBLE",
- "dispute_categories": [
- "string"
]
}, - "seller_receivable_breakdown": {
- "platform_fees": [
- {
- "amount": {
- "currency_code": "str",
- "value": "string"
}, - "payee": {
- "email_address": "string",
- "merchant_id": "stringstrings"
}
}
], - "gross_amount": {
- "currency_code": "str",
- "value": "string"
}, - "paypal_fee": {
- "currency_code": "str",
- "value": "string"
}, - "paypal_fee_in_receivable_currency": {
- "currency_code": "str",
- "value": "string"
}, - "net_amount": {
- "currency_code": "str",
- "value": "string"
}, - "receivable_amount": {
- "currency_code": "str",
- "value": "string"
}, - "exchange_rate": {
- "value": "string",
- "source_currency": "str",
- "target_currency": "str"
}
}, - "processor_response": {
- "avs_code": "A",
- "cvv_code": "E",
- "response_code": "0000",
- "payment_advice_code": "01"
}, - "create_time": "stringstringstringst",
- "update_time": "stringstringstringst"
}
The capture identification-related fields. Includes the invoice ID, custom ID, note to payer, and soft descriptor.
invoice_id | string [ 1 .. 127 ] characters ^.{1,127}$ 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. |
note_to_payer | string [ 1 .. 255 ] characters ^.{1,255}$ An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives. |
{- "invoice_id": "string",
- "note_to_payer": "string"
}
Captures either a portion or the full authorized amount of an authorized payment.
invoice_id | string [ 1 .. 127 ] characters ^.{1,127}$ 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. |
note_to_payer | string [ 1 .. 255 ] characters ^.{1,255}$ An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives. |
final_capture | boolean Default: false Indicates whether you can make additional captures against the authorized payment. Set to |
object (payment_instruction) Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order. | |
soft_descriptor | string <= 22 characters The payment descriptor on the payer's account statement. |
object (Money) 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. |
{- "invoice_id": "string",
- "note_to_payer": "string",
- "final_capture": false,
- "payment_instruction": {
- "platform_fees": [
- {
- "amount": {
- "currency_code": "str",
- "value": "string"
}, - "payee": {
- "email_address": "string",
- "merchant_id": "stringstrings"
}
}
], - "payee_receivable_fx_rate_id": "string",
- "disbursement_mode": "INSTANT"
}, - "soft_descriptor": "string",
- "amount": {
- "currency_code": "str",
- "value": "string"
}
}
The status and status details of a captured payment.
status | string (Capture Status) The status of the captured payment.
| ||||||||||||||
object (capture_status_details) The details of the captured payment status. |
{- "status": "COMPLETED",
- "status_details": {
- "reason": "BUYER_COMPLAINT"
}
}
The details of the captured payment status.
reason | string (Capture Incomplete Reason) [ 1 .. 64 ] characters ^[A-Z_]+$ The reason why the captured payment status is
|
{- "reason": "BUYER_COMPLAINT"
}
A captured payment.
status | string (Capture Status) The status of the captured payment.
| ||||||||||||||
object (capture_status_details) The details of the captured payment status. | |||||||||||||||
id | string The PayPal-generated ID for the captured payment. | ||||||||||||||
invoice_id | string 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. | ||||||||||||||
custom_id | string <= 255 characters The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. | ||||||||||||||
final_capture | boolean Default: false Indicates whether you can make additional captures against the authorized payment. Set to | ||||||||||||||
disbursement_mode | string (disbursement_mode) [ 1 .. 16 ] characters ^[A-Z_]+$ Default: "INSTANT" The funds that are held on behalf of the merchant.
| ||||||||||||||
Array of objects (Link Description) An array of related HATEOAS links. | |||||||||||||||
object (Money) The amount for this captured payment. | |||||||||||||||
object (network_transaction_reference) Reference values used by the card network to identify a transaction. | |||||||||||||||
object (seller_protection) The level of protection offered as defined by PayPal Seller Protection for Merchants. | |||||||||||||||
object (Seller Receivable Breakdown) The detailed breakdown of the capture activity. This is not available for transactions that are in pending state. | |||||||||||||||
object (processor_response) An object that provides additional processor information for a direct credit card transaction. | |||||||||||||||
create_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction occurred, in Internet date and time format. | ||||||||||||||
update_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction was last updated, in Internet date and time format. | ||||||||||||||
object (Payment Supplementary Data) An object that provides supplementary/additional data related to a payment transaction. | |||||||||||||||
object (payee_base) The details associated with the merchant for this transaction. |
{- "status": "COMPLETED",
- "status_details": {
- "reason": "BUYER_COMPLAINT"
}, - "id": "string",
- "invoice_id": "string",
- "custom_id": "string",
- "final_capture": false,
- "disbursement_mode": "INSTANT",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "amount": {
- "currency_code": "str",
- "value": "string"
}, - "network_transaction_reference": {
- "id": "stringstr",
- "date": "stri",
- "acquirer_reference_number": "string",
- "network": "VISA"
}, - "seller_protection": {
- "status": "ELIGIBLE",
- "dispute_categories": [
- "string"
]
}, - "seller_receivable_breakdown": {
- "platform_fees": [
- {
- "amount": {
- "currency_code": "str",
- "value": "string"
}, - "payee": {
- "email_address": "string",
- "merchant_id": "stringstrings"
}
}
], - "gross_amount": {
- "currency_code": "str",
- "value": "string"
}, - "paypal_fee": {
- "currency_code": "str",
- "value": "string"
}, - "paypal_fee_in_receivable_currency": {
- "currency_code": "str",
- "value": "string"
}, - "net_amount": {
- "currency_code": "str",
- "value": "string"
}, - "receivable_amount": {
- "currency_code": "str",
- "value": "string"
}, - "exchange_rate": {
- "value": "string",
- "source_currency": "str",
- "target_currency": "str"
}
}, - "processor_response": {
- "avs_code": "A",
- "cvv_code": "E",
- "response_code": "0000",
- "payment_advice_code": "01"
}, - "create_time": "stringstringstringst",
- "update_time": "stringstringstringst",
- "supplementary_data": {
- "related_ids": {
- "order_id": "string",
- "authorization_id": "string",
- "capture_id": "string"
}
}, - "payee": {
- "email_address": "string",
- "merchant_id": "stringstrings"
}
}
The payment card to use to fund a payment. Can be a credit or debit card.
name | string [ 1 .. 300 ] characters ^.{1,300}$ The card holder's name as it appears on the card. |
number | string [ 13 .. 19 ] characters ^[0-9]{13,19}$ The primary account number (PAN) for the payment card. |
security_code | string [ 3 .. 4 ] characters ^[0-9]{3,4}$ The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when |
expiry | string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$ The card expiration year and month, in Internet date format. |
object (Portable Postal Address (Medium-Grained)) The billing address for this card. Supports only the | |
object (card_attributes) Additional attributes associated with the use of this card. |
{- "name": "string",
- "number": "stringstrings",
- "security_code": "stri",
- "expiry": "string",
- "billing_address": {
- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}, - "attributes": {
- "customer": {
- "id": "string",
- "email_address": "string",
- "phone": {
- "phone_type": "FAX",
- "phone_number": {
- "national_number": "string"
}
}, - "merchant_customer_id": "string"
}, - "vault": {
- "store_in_vault": "ON_SUCCESS"
}, - "verification": {
- "method": "SCA_ALWAYS"
}
}
}
The payment card to use to fund a payment. Can be a credit or debit card.
name | string [ 1 .. 300 ] characters ^.{1,300}$ The card holder's name as it appears on the card. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
number | string [ 13 .. 19 ] characters ^[0-9]{13,19}$ The primary account number (PAN) for the payment card. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
expiry | string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$ The card expiration year and month, in Internet date format. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
card_type | string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
type | string (card_type) [ 1 .. 255 ] characters ^[A-Z_]+$ The payment card type.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
brand | string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Portable Postal Address (Medium-Grained)) The billing address for this card. Supports only the |
{- "name": "string",
- "number": "stringstrings",
- "expiry": "string",
- "card_type": "VISA",
- "type": "CREDIT",
- "brand": "VISA",
- "billing_address": {
- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
}
The API caller can opt in to verify the card through PayPal offered verification services (e.g. Smart Dollar Auth, 3DS).
method | string [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Default: "SCA_WHEN_REQUIRED" The method used for card verification.
|
{- "method": "SCA_ALWAYS"
}
Additional attributes associated with the use of this card.
object (card_customer) The details about a customer in PayPal's system of record. | |
object (vault_instruction_base) Instruction to vault the card based on the specified strategy. | |
object (Card Verification) Instruction to optionally verify the card based on the specified strategy. |
{- "customer": {
- "id": "string",
- "email_address": "string",
- "phone": {
- "phone_type": "FAX",
- "phone_number": {
- "national_number": "string"
}
}, - "merchant_customer_id": "string"
}, - "vault": {
- "store_in_vault": "ON_SUCCESS"
}, - "verification": {
- "method": "SCA_ALWAYS"
}
}
Additional attributes associated with the use of this card.
object (Card Verification) Instruction to optionally verify the card based on the specified strategy. |
{- "verification": {
- "method": "SCA_ALWAYS"
}
}
Additional attributes associated with the use of this card.
object (card_vault_response) The details about a saved Card payment source. |
{- "vault": {
- "id": "string",
- "status": "VAULTED",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "customer": {
- "id": "string",
- "email_address": "string",
- "phone": {
- "phone_type": "FAX",
- "phone_number": {
- "national_number": "string"
}
}, - "merchant_customer_id": "string"
}
}
}
The card network or brand. Applies to credit, debit, gift, and payment cards.
The card network or brand. Applies to credit, debit, gift, and payment cards.
Enum: | Description |
---|---|
VISA | Visa card. |
MASTERCARD | Mastecard card. |
DISCOVER | Discover card. |
AMEX | American Express card. |
SOLO | Solo debit card. |
JCB | Japan Credit Bureau card. |
STAR | Military Star card. |
DELTA | Delta Airlines card. |
SWITCH | Switch credit card. |
MAESTRO | Maestro credit card. |
CB_NATIONALE | Carte Bancaire (CB) credit card. |
CONFIGOGA | Configoga credit card. |
CONFIDIS | Confidis credit card. |
ELECTRON | Visa Electron credit card. |
CETELEM | Cetelem credit card. |
CHINA_UNION_PAY | China union pay credit card. |
DINERS | The Diners Club International banking and payment services capability network owned by Discover Financial Services (DFS), one of the most recognized brands in US financial services. |
ELO | The Brazilian Elo card payment network. |
HIPER | The Hiper - Ingenico ePayment network. |
HIPERCARD | The Brazilian Hipercard payment network that's widely accepted in the retail market. |
RUPAY | The RuPay payment network. |
GE | The GE Credit Union 3Point card payment network. |
SYNCHRONY | The Synchrony Financial (SYF) payment network. |
EFTPOS | The Electronic Fund Transfer At Point of Sale(EFTPOS) Debit card payment network. |
UNKNOWN | UNKNOWN payment network. |
"VISA"
The details about a customer in PayPal's system of record.
id | string (merchant_partner_customer_id) [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$ The unique ID for a customer generated by PayPal. |
email_address | string <merchant_common_email_address_v2> (email) [ 3 .. 254 ] characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-... Email address of the buyer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants. For all other use cases we do not expect partners/merchant to send email_address of their customer. |
object (phone_with_type) The phone number of the buyer as provided to the merchant or on file with the merchant. The | |
merchant_customer_id | string [ 1 .. 64 ] characters ^[0-9a-zA-Z-_.^*$@#]+$ Merchants and partners may already have a data-store where their customer information is persisted. Use merchant_customer_id to associate the PayPal-generated customer.id to your representation of a customer. |
{- "id": "string",
- "email_address": "string",
- "phone": {
- "phone_type": "FAX",
- "phone_number": {
- "national_number": "string"
}
}, - "merchant_customer_id": "string"
}
Customizes the payer experience during the 3DS Approval for payment.
return_url | string <uri> (url) [ 10 .. 4000 ] characters The URL where the customer will be redirected upon successfully completing the 3DS challenge. |
cancel_url | string <uri> (url) [ 10 .. 4000 ] characters The URL where the customer will be redirected upon cancelling the 3DS challenge. |
{- "return_url": "string",
- "cancel_url": "string"
}
Representation of card details as received in the request.
last_digits | string [ 2 .. 4 ] characters [0-9]{2,} The last digits of the payment card. |
expiry | string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$ The card expiration year and month, in Internet date format. |
{- "last_digits": "stri",
- "expiry": "string"
}
Provides additional details to process a payment using a card
that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:
payment_type=ONE_TIME
is compatible only with payment_initiator=CUSTOMER
.usage=FIRST
is compatible only with payment_initiator=CUSTOMER
.previous_transaction_reference
or previous_network_transaction_reference
is compatible only with payment_initiator=MERCHANT
.previous_transaction_reference
and previous_network_transaction_reference
- can be present in the request.payment_initiator required | string (payment_initiator) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ The person or party who initiated or triggered the payment.
| ||||||||
payment_type required | string (stored_payment_source_payment_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Indicates the type of the stored payment_source payment.
| ||||||||
usage | string (stored_payment_source_usage_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Default: "DERIVED" Indicates if this is a
| ||||||||
object (network_transaction_reference) Reference values used by the card network to identify a transaction. |
{- "payment_initiator": "CUSTOMER",
- "payment_type": "ONE_TIME",
- "usage": "FIRST",
- "previous_network_transaction_reference": {
- "id": "stringstr",
- "date": "stri",
- "acquirer_reference_number": "string",
- "network": "VISA"
}
}
Type of card. i.e Credit, Debit and so on.
Type of card. i.e Credit, Debit and so on.
Enum: | Description |
---|---|
CREDIT | A credit card. |
DEBIT | A debit card. |
PREPAID | A Prepaid card. |
STORE | A store card. |
UNKNOWN | Card type cannot be determined. |
"CREDIT"
The details about a saved Card payment source.
id | string [ 1 .. 255 ] characters The PayPal-generated ID for the saved payment source. | ||||||||
status | string (Vault Status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ The vault status.
| ||||||||
Array of objects (Link Description) [ 1 .. 10 ] items An array of request-related HATEOAS links. | |||||||||
object (card_customer) The details about a customer in PayPal's system of record. |
{- "id": "string",
- "status": "VAULTED",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "customer": {
- "id": "string",
- "email_address": "string",
- "phone": {
- "phone_type": "FAX",
- "phone_number": {
- "national_number": "string"
}
}, - "merchant_customer_id": "string"
}
}
Common response fields for all payment methods.
can_be_vaulted | boolean Default: "false" Indicates if the payment method can be vaulted or not. A true value indicates the payment method can be vaulted using our vaults product. If false, vaulting is not currently supported for this payment method. |
{- "can_be_vaulted": "false"
}
The 2-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
The 2-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
"st"
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
"st"
The 2-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
The 2-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
"st"
The cryptocurrency symbol or code ticker options. Assigned by liquidity providers and exchanges.
The cryptocurrency symbol or code ticker options. Assigned by liquidity providers and exchanges.
Enum: | Description |
---|---|
BTC | The ticker symbol for Bitcoin. https://en.wikipedia.org/wiki/Bitcoin. |
ETH | The ticker symbol for Ethereum. https://en.wikipedia.org/wiki/Ethereum. |
BCH | The ticker symbol for Bitcoin Cash. https://en.wikipedia.org/wiki/Bitcoin_Cash. |
LTC | The ticker symbol for Litecoin. https://en.wikipedia.org/wiki/Litecoin. |
"BTC"
The three-character ISO-4217 currency code that identifies the currency.
The three-character ISO-4217 currency code that identifies the currency.
"str"
The details about a customer in PayPal's system of record.
id | string (merchant_partner_customer_id) [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$ The unique ID for a customer generated by PayPal. |
email_address | string <merchant_common_email_address_v2> (email) [ 3 .. 254 ] characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-... Email address of the buyer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants. For all other use cases we do not expect partners/merchant to send email_address of their customer. |
object (phone_with_type) The phone number of the buyer as provided to the merchant or on file with the merchant. The |
{- "id": "string",
- "email_address": "string",
- "phone": {
- "phone_type": "FAX",
- "phone_number": {
- "national_number": "string"
}
}
}
The details about a customer in PayPal's system of record.
id | string (merchant_partner_customer_id) [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$ The unique ID for a customer generated by PayPal. |
email_address | string <merchant_common_email_address_v2> (email) [ 3 .. 254 ] characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-... Email address of the buyer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants. For all other use cases we do not expect partners/merchant to send email_address of their customer. |
{- "id": "string",
- "email_address": "string"
}
The details about a customer in PayPal's system of record.
id | string (merchant_partner_customer_id) [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$ The unique ID for a customer generated by PayPal. |
{- "id": "string"
}
Customer who is making a purchase from the merchant/partner.
id | string [ 1 .. 36 ] characters ^[0-9a-zA-Z_-]+$ The unique ID for a customer in merchant's or partner's system of records. |
country_code | string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$ Country from which the customer is purchasing products/services from the merchant/partner. Result will factor in local payment methods that are available in the country mentioned. Value should be in the 2-character ISO 3166-1 code format. |
object (Customer Channel) Channel through which the request is being posted. This object intends to collect information such as browser, operating system, device of the buyer. If both channel and User-Agent header are passed, data passed in the channel object takes precedence and User-Agent header will be used for information not provided in channel object. | |
string <ppaas_common_email_address_v2> (email_address) [ 3 .. 254 ] characters ^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za... The email address of the customer. | |
object (Phone) The phone number of the customer. |
{- "id": "string",
- "country_code": "string",
- "channel": {
- "browser_type": "string",
- "client_os": "string",
- "device_type": "string"
}, - "email": "string",
- "phone": {
- "country_code": "str",
- "national_number": "string"
}
}
Channel through which the request is being posted.
browser_type | string [ 1 .. 30 ] characters ^[0-9a-zA-Z_,. -]+$ The browser used by the customer. Example: Safari, Chrome, etc. |
client_os | string [ 1 .. 30 ] characters ^[0-9a-zA-Z_,. -]+$ The operating system on the device used by the customer. Example: iOS 16.5, Android 30, etc. |
device_type | string [ 1 .. 30 ] characters ^[0-9a-zA-Z_,. -]+$ The type of device used by the customer. Example: Mobile, Desktop, Tablet, etc. |
{- "browser_type": "string",
- "client_os": "string",
- "device_type": "string"
}
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time
type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time
type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
"stringstri"
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 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.
"stringstringstringst"
The year and month, in ISO-8601 YYYY-MM
date format. See Internet date and time format.
The year and month, in ISO-8601 YYYY-MM
date format. See Internet date and time format.
"strings"
The year and month, in ISO-8601 YYYY-MM
date format. See Internet date and time format.
The year and month, in ISO-8601 YYYY-MM
date format. See Internet date and time format.
"strings"
The funds that are held on behalf of the merchant.
The funds that are held on behalf of the merchant.
Enum: | Description |
---|---|
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. |
"INSTANT"
Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor.
Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor.
Enum: | Description |
---|---|
MASTERCARD_NON_3D_SECURE_TRANSACTION | Mastercard non-3-D Secure transaction. |
MASTERCARD_ATTEMPTED_AUTHENTICATION_TRANSACTION | Mastercard attempted authentication transaction. |
MASTERCARD_FULLY_AUTHENTICATED_TRANSACTION | Mastercard fully authenticated transaction. |
FULLY_AUTHENTICATED_TRANSACTION | VISA, AMEX, JCB, DINERS CLUB fully authenticated transaction. |
ATTEMPTED_AUTHENTICATION_TRANSACTION | VISA, AMEX, JCB, DINERS CLUB attempted authentication transaction. |
NON_3D_SECURE_TRANSACTION | VISA, AMEX, JCB, DINERS CLUB non-3-D Secure transaction. |
"MASTERCARD_NON_3D_SECURE_TRANSACTION"
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 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.
"string"
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 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.
"string"
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 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.
"string"
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 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.
"string"
Status of Authentication eligibility.
Status of Authentication eligibility.
Enum: | Description |
---|---|
Y | Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl. |
N | No. The bank is not participating in 3-D Secure protocol. |
U | Unavailable. The DS or ACS is not available for authentication at the time of the request. |
B | Bypass. The merchant authentication rule is triggered to bypass authentication. |
"Y"
The error details.
name required | string The human-readable, unique name of the error. |
message required | string The message that describes the error. |
debug_id required | string The PayPal internal ID. Used for correlation purposes. |
Array of objects (Error Details) An array of additional details about the error. | |
Array of objects (Link Description) An array of request-related HATEOAS links. |
{- "name": "string",
- "message": "string",
- "debug_id": "string",
- "details": [
- {
- "field": "string",
- "value": "string",
- "location": "body",
- "issue": "string",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "description": "string"
}
], - "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
]
}
The error details. Required for client-side 4XX
errors.
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 Default: "body" The location of the field that caused the error. Value is |
issue required | string The unique, fine-grained application-level error code. |
Array of objects (Link Description) [ 1 .. 4 ] items An array of request-related HATEOAS links that are either relevant to the issue by providing additional information or offering potential resolutions. | |
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. |
{- "field": "string",
- "value": "string",
- "location": "body",
- "issue": "string",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "description": "string"
}
The exchange rate that determines the amount to convert from one currency to another currency.
value | string 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. |
source_currency | string <ppaas_common_currency_code_v2> (currency_code) = 3 characters The source currency from which to convert an amount. |
target_currency | string <ppaas_common_currency_code_v2> (currency_code) = 3 characters The target currency to which to convert an amount. |
{- "value": "string",
- "source_currency": "str",
- "target_currency": "str"
}
Customizes the payer experience during the approval process for the payment.
brand_name | string [ 1 .. 127 ] characters ^.*$ The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode. | ||||||||
shipping_preference | string [ 1 .. 24 ] characters ^[A-Z_]+$ Default: "GET_FROM_FILE" The location from which the shipping address is derived.
| ||||||||
locale | string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[... The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, | ||||||||
return_url | string <uri> (url) The URL where the customer is redirected after the customer approves the payment. | ||||||||
cancel_url | string <uri> (url) The URL where the customer is redirected after the customer cancels the payment. |
{- "brand_name": "string",
- "shipping_preference": "GET_FROM_FILE",
- "locale": "string",
- "return_url": "string",
- "cancel_url": "string"
}
Customizes the payer experience during the approval process for the payment.
locale | string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[... The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, |
return_url | string <uri> (url) The URL where the customer is redirected after the customer approves the payment. |
cancel_url | string <uri> (url) The URL where the customer is redirected after the customer cancels the payment. |
{- "locale": "string",
- "return_url": "string",
- "cancel_url": "string"
}
The payment card used to fund a Google Pay payment. Can be a credit or debit card.
name | string [ 1 .. 300 ] characters ^.{1,300}$ The card holder's name as it appears on the card. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
type | string (card_type) [ 1 .. 255 ] characters ^[A-Z_]+$ The payment card type.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
brand | string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Portable Postal Address (Medium-Grained)) The billing address for this card. Supports only the |
{- "name": "string",
- "type": "CREDIT",
- "brand": "VISA",
- "billing_address": {
- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
}
Details shared by Google for the merchant to be shared with PayPal. This is required to process the transaction using the Google Pay payment method.
message_id | string [ 1 .. 250 ] characters ^.*$ A unique ID that identifies the message in case it needs to be revoked or located at a later time. | ||||||
message_expiration | string = 13 characters \d{13} Date and time at which the message expires as UTC milliseconds since epoch. Integrators should reject any message that's expired. | ||||||
payment_method required | string = 4 characters The type of the payment credential. Currently, only CARD is supported.
| ||||||
authentication_method required | string [ 1 .. 50 ] characters Authentication Method which is used for the card transaction.
| ||||||
cryptogram | string [ 1 .. 2000 ] characters Base-64 cryptographic identifier used by card schemes to validate the token verification result. This is a conditionally required field if authentication_method is CRYPTOGRAM_3DS. | ||||||
eci_indicator | string [ 1 .. 256 ] characters ^.*$ Electronic Commerce Indicator may not always be present. It is only returned for tokens on the Visa card network. This value is passed through in the payment authorization request. |
{- "message_id": "string",
- "message_expiration": "stringstrings",
- "payment_method": "CARD",
- "authentication_method": "PAN_ONLY",
- "cryptogram": "string",
- "eci_indicator": "string"
}
The identifier of the instrument.
The identifier of the instrument.
"string"
An Internet Protocol address (IP address). This address assigns a numerical label to each device that is connected to a computer network through the Internet Protocol. Supports IPv4 and IPv6 addresses.
An Internet Protocol address (IP address). This address assigns a numerical label to each device that is connected to a computer network through the Internet Protocol. Supports IPv4 and IPv6 addresses.
"strings"
The details for the items to be purchased.
name required | string [ 1 .. 127 ] characters The item name or title. |
quantity required | string <= 10 characters ^[1-9][0-9]{0,9}$ The item quantity. Must be a whole number. |
description | string <= 127 characters The detailed item description. |
sku | string <= 127 characters The stock keeping unit (SKU) for the item. |
url | string <uri> [ 1 .. 2048 ] characters The URL to the item being purchased. Visible to buyer and used in buyer experiences. |
image_url | string <uri> [ 1 .. 2048 ] characters ^(https:)([/|.|\w|\s|-])*\.(?:jpg|gif|png|jpe... The URL of the item's image. File type and size restrictions apply. An image that violates these restrictions will not be honored. |
object (universal_product_code) The Universal Product Code of the item. |
{- "name": "string",
- "quantity": "string",
- "description": "string",
- "sku": "string",
- "upc": {
- "type": "UPC-A",
- "code": "string"
}
}
The details for the items to be purchased.
name required | string [ 1 .. 127 ] characters The item name or title. | ||||||||
quantity required | string <= 10 characters ^[1-9][0-9]{0,9}$ The item quantity. Must be a whole number. | ||||||||
description | string <= 127 characters The detailed item description. | ||||||||
sku | string <= 127 characters The stock keeping unit (SKU) for the item. | ||||||||
url | string <uri> [ 1 .. 2048 ] characters The URL to the item being purchased. Visible to buyer and used in buyer experiences. | ||||||||
category | string [ 1 .. 20 ] characters The item category type.
| ||||||||
image_url | string <uri> [ 1 .. 2048 ] characters ^(https:)([/|.|\w|\s|-])*\.(?:jpg|gif|png|jpe... The URL of the item's image. File type and size restrictions apply. An image that violates these restrictions will not be honored. | ||||||||
required | object (Money) The item price or rate per unit. If you specify | ||||||||
object (Money) The item tax for each unit. If | |||||||||
object (universal_product_code) The Universal Product Code of the item. |
{- "name": "string",
- "quantity": "string",
- "description": "string",
- "sku": "string",
- "category": "DIGITAL_GOODS",
- "unit_amount": {
- "currency_code": "str",
- "value": "string"
}, - "tax": {
- "currency_code": "str",
- "value": "string"
}, - "upc": {
- "type": "UPC-A",
- "code": "string"
}
}
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
"string"
The level 2 card processing data collections. If your merchant account has been configured for Level 2 processing this field will be passed to the processor on your behalf. Please contact your PayPal Technical Account Manager to define level 2 data for your business.
invoice_id | string [ 1 .. 127 ] characters ^[\w‘\-.,":;\!?]*$ Use this field to pass a purchase identification value of up to 127 ASCII characters. The length of this field will be adjusted to meet network specifications (25chars for Visa and Mastercard, 17chars for Amex), and the original invoice ID will still be displayed in your existing reports. |
object (Money) Use this field to break down the amount of tax included in the total purchase amount. The value provided here will not add to the total purchase amount. The value can't be negative, and in most cases, it must be greater than zero in order to qualify for lower interchange rates. Value, by country, is:
|
{- "invoice_id": "string",
- "tax_total": {
- "currency_code": "str",
- "value": "string"
}
}
The level 3 card processing data collections, If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf. Please contact your PayPal Technical Account Manager to define level 3 data for your business.
ships_from_postal_code | string [ 1 .. 60 ] characters ^[a-zA-Z0-9_'.-]*$ Use this field to specify the postal code of the shipping location. |
Array of objects (line_item) [ 1 .. 100 ] items A list of the items that were purchased with this payment. If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf. | |
object (Money) Use this field to break down the shipping cost included in the total purchase amount. The value provided here will not add to the total purchase amount. The value cannot be negative. | |
object (Money) Use this field to break down the duty amount included in the total purchase amount. The value provided here will not add to the total purchase amount. The value cannot be negative. | |
object (Money) Use this field to break down the discount amount included in the total purchase amount. The value provided here will not add to the total purchase amount. The value cannot be negative. | |
object (Portable Postal Address (Medium-Grained)) The address of the person to whom to ship the items. Supports only the |
{- "ships_from_postal_code": "string",
- "line_items": [
- {
- "name": "string",
- "quantity": "string",
- "description": "string",
- "sku": "string",
- "upc": {
- "type": "UPC-A",
- "code": "string"
}, - "commodity_code": "string",
- "unit_of_measure": "string",
- "unit_amount": {
- "currency_code": "str",
- "value": "string"
}, - "tax": {
- "currency_code": "str",
- "value": "string"
}, - "discount_amount": {
- "currency_code": "str",
- "value": "string"
}, - "total_amount": {
- "currency_code": "str",
- "value": "string"
}
}
], - "shipping_amount": {
- "currency_code": "str",
- "value": "string"
}, - "duty_amount": {
- "currency_code": "str",
- "value": "string"
}, - "discount_amount": {
- "currency_code": "str",
- "value": "string"
}, - "shipping_address": {
- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
}
Liability shift indicator. The outcome of the issuer's authentication.
Liability shift indicator. The outcome of the issuer's authentication.
Enum: | Description |
---|---|
NO | Liability is with the merchant. |
POSSIBLE | Liability may shift to the card issuer. |
UNKNOWN | The authentication system is not available. |
"NO"
The line items for this purchase. If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf.
name required | string [ 1 .. 127 ] characters The item name or title. |
quantity required | string <= 10 characters ^[1-9][0-9]{0,9}$ The item quantity. Must be a whole number. |
description | string <= 127 characters The detailed item description. |
sku | string <= 127 characters The stock keeping unit (SKU) for the item. |
url | string <uri> [ 1 .. 2048 ] characters The URL to the item being purchased. Visible to buyer and used in buyer experiences. |
image_url | string <uri> [ 1 .. 2048 ] characters ^(https:)([/|.|\w|\s|-])*\.(?:jpg|gif|png|jpe... The URL of the item's image. File type and size restrictions apply. An image that violates these restrictions will not be honored. |
object (universal_product_code) The Universal Product Code of the item. | |
commodity_code | string [ 1 .. 12 ] characters ^[a-zA-Z0-9_'.-]*$ Code used to classify items purchased and track the total amount spent across various categories of products and services. Different corporate purchasing organizations may use different standards, but the United Nations Standard Products and Services Code (UNSPSC) is frequently used. |
unit_of_measure | string [ 1 .. 12 ] characters ^[a-zA-Z0-9_'.-]*$ Unit of measure is a standard used to express the magnitude of a quantity in international trade. Most commonly used (but not limited to) examples are: Acre (ACR), Ampere (AMP), Centigram (CGM), Centimetre (CMT), Cubic inch (INQ), Cubic metre (MTQ), Fluid ounce (OZA), Foot (FOT), Hour (HUR), Item (ITM), Kilogram (KGM), Kilometre (KMT), Kilowatt (KWT), Liquid gallon (GLL), Liter (LTR), Pounds (LBS), Square foot (FTK). |
required | object (Money) The item price or rate per unit. Must equal |
object (Money) The item tax for each unit. Must equal | |
object (Money) Use this field to break down the discount amount included in the total purchase amount. The value provided here will not add to the total purchase amount. The value cannot be negative. | |
object (Money) The subtotal for all items. Must equal the sum of (items[].unit_amount * items[].quantity) for all items. item_total.value can not be a negative number. |
{- "name": "string",
- "quantity": "string",
- "description": "string",
- "sku": "string",
- "upc": {
- "type": "UPC-A",
- "code": "string"
}, - "commodity_code": "string",
- "unit_of_measure": "string",
- "unit_amount": {
- "currency_code": "str",
- "value": "string"
}, - "tax": {
- "currency_code": "str",
- "value": "string"
}, - "discount_amount": {
- "currency_code": "str",
- "value": "string"
}, - "total_amount": {
- "currency_code": "str",
- "value": "string"
}
}
The request-related HATEOAS link information.
href required | string The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the |
rel required | string 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. |
{- "href": "string",
- "rel": "string",
- "method": "GET"
}
The request-related HATEOAS link information.
href required | string The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the |
rel required | string 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. |
{- "href": "string",
- "rel": "string",
- "method": "GET"
}
The request-related HATEOAS link information.
href required | string The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the |
rel required | string 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. |
{- "href": "string",
- "rel": "string",
- "method": "GET"
}
The unique ID for a customer generated by PayPal.
The unique ID for a customer generated by PayPal.
"string"
The currency and amount for a financial transaction, such as a balance or payment due.
currency_code required | string <ppaas_common_currency_code_v2> (currency_code) = 3 characters The three-character ISO-4217 currency code that identifies the currency. |
value required | string <= 32 characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ The value, which might be:
|
{- "currency_code": "str",
- "value": "string"
}
The full name representation like Mr J Smith.
The full name representation like Mr J Smith.
"string"
The name of the party.
given_name | string <= 140 characters When the party is a person, the party's given, or first, name. |
surname | string <= 140 characters 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. |
{- "given_name": "string",
- "surname": "string"
}
The name of the party.
full_name | string <= 300 characters When the party is a person, the party's full name. |
{- "full_name": "string"
}
The name of the party.
full_name | string <= 300 characters When the party is a person, the party's full name. |
{- "full_name": "string"
}
The net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the merchant holds their funds.
object (Money) The net amount debited from the merchant's PayPal account. | |
object (Money) The converted payable amount. | |
object (exchange_rate) The exchange rate that determines the amount that was debited from the merchant's PayPal account. |
{- "payable_amount": {
- "currency_code": "str",
- "value": "string"
}, - "converted_amount": {
- "currency_code": "str",
- "value": "string"
}, - "exchange_rate": {
- "value": "string",
- "source_currency": "str",
- "target_currency": "str"
}
}
The Third Party Network token used to fund a payment.
number required | string [ 13 .. 19 ] characters ^[0-9]{13,19}$ Third party network token number. | ||||||||||||||
cryptogram | string [ 28 .. 32 ] characters ^.*$ An Encrypted one-time use value that's sent along with Network Token. This field is not required to be present for recurring transactions. | ||||||||||||||
token_requestor_id | string [ 1 .. 11 ] characters ^[0-9A-Z_]+$ A TRID, or a Token Requestor ID, is an identifier used by merchants to request network tokens from card networks. A TRID is a precursor to obtaining a network token for a credit card primary account number (PAN), and will aid in enabling secure card on file (COF) payments and reducing fraud. | ||||||||||||||
expiry required | string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$ The card expiration year and month, in Internet date format. | ||||||||||||||
eci_flag | string (eci_flag) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor.
|
{- "number": "stringstrings",
- "cryptogram": "stringstringstringstringstri",
- "token_requestor_id": "string",
- "expiry": "string",
- "eci_flag": "MASTERCARD_NON_3D_SECURE_TRANSACTION"
}
Reference values used by the card network to identify a transaction.
id required | string [ 9 .. 36 ] characters ^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$ Transaction reference id returned by the scheme. For Visa and Amex, this is the "Tran id" field in response. For MasterCard, this is the "BankNet reference id" field in response. For Discover, this is the "NRID" field in response. The pattern we expect for this field from Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric and Paysecure is alphanumeric with special character -. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
date | string = 4 characters ^[0-9]+$ The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
acquirer_reference_number | string [ 1 .. 36 ] characters ^[a-zA-Z0-9]+$ Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
network | string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$ Name of the card network through which the transaction was routed.
|
{- "id": "stringstr",
- "date": "stri",
- "acquirer_reference_number": "string",
- "network": "VISA"
}
Transactions status result identifier. The outcome of the issuer's authentication.
Transactions status result identifier. The outcome of the issuer's authentication.
Enum: | Description |
---|---|
Y | Successful authentication. |
N | Failed authentication / account not verified / transaction denied. |
U | Unable to complete authentication. |
A | Successful attempts transaction. |
C | Challenge required for authentication. |
R | Authentication rejected (merchant must not submit for authorization). |
D | Challenge required; decoupled authentication confirmed. |
I | Informational only; 3DS requestor challenge preference acknowledged. |
"Y"
The JSON patch object to apply partial updates to resources.
op required | string The operation.
| ||||||||||||||||||||||||||
path | string The JSON Pointer to the target document location at which to complete the operation. | ||||||||||||||||||||||||||
value | any (Patch Value) The value to apply. The | ||||||||||||||||||||||||||
from | string The JSON Pointer to the target document location from which to move the value. Required for the |
{- "op": "add",
- "path": "string",
- "value": null,
- "from": "string"
}
The merchant who receives the funds and fulfills the order. The merchant is also known as the payee.
email_address | string <merchant_common_email_address_v2> (email) [ 3 .. 254 ] characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-... The email address of merchant. |
merchant_id | string <ppaas_payer_id_v3> (PayPal Account Identifier) = 13 characters ^[2-9A-HJ-NP-Z]{13}$ The encrypted PayPal account ID of the merchant. |
{- "email_address": "string",
- "merchant_id": "stringstrings"
}
The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee.
email_address | string <merchant_common_email_address_v2> (email) [ 3 .. 254 ] characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-... The email address of merchant. |
merchant_id | string <ppaas_payer_id_v3> (PayPal Account Identifier) = 13 characters ^[2-9A-HJ-NP-Z]{13}$ The encrypted PayPal account ID of the merchant. |
{- "email_address": "string",
- "merchant_id": "stringstrings"
}
The customer who approves and pays for the order. The customer is also known as the payer.
email_address | string <merchant_common_email_address_v2> (email) [ 3 .. 254 ] characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-... The email address of the payer. |
{- "email_address": "string"
}
List of payment methods.
object (Response for PayPal) PayPal payment method. | |
object (Response for Venmo) Venmo payment method. | |
object (Common response fields) PayPal Credit payment method. | |
object (Common response fields) PayPal Pay Later payment method. |
{- "paypal": {
- "can_be_vaulted": "false",
- "eligible_in_paypal_network": true,
- "recommended": "false",
- "recommended_priority": 1
}, - "venmo": {
- "can_be_vaulted": "false",
- "eligible_in_paypal_network": true,
- "recommended": "false",
- "recommended_priority": 1
}, - "paypal_credit": {
- "can_be_vaulted": "false"
}, - "paypal_pay_later": {
- "can_be_vaulted": "false"
}
}
The supplementary data.
object (Related Identifiers) Identifiers related to a specific resource. |
{- "related_ids": {
- "order_id": "string",
- "authorization_id": "string",
- "capture_id": "string"
}
}
The person or party who initiated or triggered the payment.
The person or party who initiated or triggered the payment.
Enum: | Description |
---|---|
CUSTOMER | Payment is initiated with the active engagement of the customer. e.g. a customer checking out on a merchant website. |
MERCHANT | Payment is initiated by merchant on behalf of the customer without the active engagement of customer. e.g. a merchant charging the monthly payment of a subscription to the customer. |
"CUSTOMER"
Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order.
Array of objects (platform_fee) [ 0 .. 1 ] items An array of various fees, commissions, tips, or donations. This field is only applicable to merchants that been enabled for PayPal Complete Payments Platform for Marketplaces and Platforms capability. | |||||||
payee_receivable_fx_rate_id | string [ 1 .. 4000 ] characters ^.*$ FX identifier generated returned by PayPal to be used for payment processing in order to honor FX rate (for eligible integrations) to be used when amount is settled/received into the payee account. | ||||||
disbursement_mode | string (disbursement_mode) [ 1 .. 16 ] characters ^[A-Z_]+$ Default: "INSTANT" The funds that are held payee by the marketplace/platform. This field is only applicable to merchants that been enabled for PayPal Complete Payments Platform for Marketplaces and Platforms capability.
|
{- "platform_fees": [
- {
- "amount": {
- "currency_code": "str",
- "value": "string"
}, - "payee": {
- "email_address": "string",
- "merchant_id": "stringstrings"
}
}
], - "payee_receivable_fx_rate_id": "string",
- "disbursement_mode": "INSTANT"
}
Any additional payments instructions during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability.
Array of objects (platform_fee) [ 0 .. 1 ] items Specifies the amount that the API caller will contribute to the refund being processed. The amount needs to be lower than platform_fees amount originally captured or the amount that is remaining if multiple refunds have been processed. This field is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability. |
{- "platform_fees": [
- {
- "amount": {
- "currency_code": "str",
- "value": "string"
}
}
]
}
Set of unique payment methods.
Set of unique payment methods.
Enum: | Description |
---|---|
PAYPAL | PAYPAL |
VENMO | VENMO |
PAYPAL_CREDIT | PAYPAL_CREDIT |
PAYPAL_PAY_LATER | PAYPAL_PAY_LATER |
"PAYPAL"
Vaulted instrument for a payment-method.
id | string [ 7 .. 36 ] characters ^[0-9a-zA-Z_-]+$ The PayPal-generated ID for the vault token. |
object (The vaulted payment method details) The vaulted payment method details. | |
Array of objects (Link Description) [ 1 .. 32 ] items An array of related HATEOAS links. |
{- "id": "strings",
- "payment_source": {
- "venmo": {
- "user_name": "string"
}, - "paypal": {
- "email_address": "string"
}
}, - "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
]
}
The account identifier for a PayPal account.
The account identifier for a PayPal account.
"stringstrings"
Flag that indicates if the customer is in the PayPal network. This value will be included in the response if the include_account_details flag is set to "true" in the API request.
Flag that indicates if the customer is in the PayPal network. This value will be included in the response if the include_account_details flag is set to "true" in the API request.
true
Additional attributes associated with the use of this PayPal Wallet.
object (paypal_wallet_customer) The details about a customer in PayPal's system of record. | |
object (vault_paypal_wallet_base) Attributes used to provide the instructions during vaulting of the PayPal Wallet. |
{- "customer": {
- "id": "string",
- "email_address": "string",
- "merchant_customer_id": "string"
}, - "vault": {
- "store_in_vault": "ON_SUCCESS",
- "description": "string",
- "usage_pattern": "string",
- "usage_type": "string",
- "customer_type": "CONSUMER",
- "permit_multiple_payment_tokens": false
}
}
The details about a customer in PayPal's system of record.
id | string (merchant_partner_customer_id) [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$ The unique ID for a customer generated by PayPal. |
email_address | string <merchant_common_email_address_v2> (email) [ 3 .. 254 ] characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-... Email address of the buyer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants. For all other use cases we do not expect partners/merchant to send email_address of their customer. |
merchant_customer_id | string [ 1 .. 64 ] characters ^[0-9a-zA-Z-_.^*$@#]+$ Merchants and partners may already have a data-store where their customer information is persisted. Use merchant_customer_id to associate the PayPal-generated customer.id to your representation of a customer. |
{- "id": "string",
- "email_address": "string",
- "merchant_customer_id": "string"
}
Customizes the payer experience during the approval process for payment with PayPal.
Note: Partners and Marketplaces might configurebrand_name
andshipping_preference
during partner account setup, which overrides the request values.
brand_name | string [ 1 .. 127 ] characters ^.*$ The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode. | ||||||||
shipping_preference | string [ 1 .. 24 ] characters ^[A-Z_]+$ Default: "GET_FROM_FILE" The location from which the shipping address is derived.
| ||||||||
landing_page | string [ 1 .. 13 ] characters ^[0-9A-Z_]+$ Default: "NO_PREFERENCE" The type of landing page to show on the PayPal site for customer checkout.
| ||||||||
user_action | string [ 1 .. 8 ] characters ^[0-9A-Z_]+$ Default: "CONTINUE" Configures a Continue or Pay Now checkout flow.
| ||||||||
payment_method_preference | string [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Default: "UNRESTRICTED" The merchant-preferred payment methods.
| ||||||||
locale | string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[... The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, | ||||||||
return_url | string <uri> (url) The URL where the customer will be redirected upon approving a payment. | ||||||||
cancel_url | string <uri> (url) The URL where the customer will be redirected upon cancelling the payment approval. |
{- "brand_name": "string",
- "shipping_preference": "GET_FROM_FILE",
- "landing_page": "LOGIN",
- "user_action": "CONTINUE",
- "payment_method_preference": "UNRESTRICTED",
- "locale": "string",
- "return_url": "string",
- "cancel_url": "string"
}
The phone number, in its canonical international E.164 numbering plan format.
national_number required | string [ 1 .. 14 ] characters ^[0-9]{1,14}?$ 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). |
{- "national_number": "string"
}
The phone number, in its canonical international E.164 numbering plan format.
national_number required | string [ 1 .. 14 ] characters ^[0-9]{1,14}?$ 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). |
{- "national_number": "string"
}
The phone number in its canonical international E.164 numbering plan format.
country_code | string [ 1 .. 3 ] characters ^[0-9]{1,3}?$ 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). |
national_number required | string [ 1 .. 14 ] characters ^[0-9]{1,14}?$ 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). |
{- "country_code": "str",
- "national_number": "string"
}
The phone number in its canonical international E.164 numbering plan format.
country_code required | string [ 1 .. 3 ] characters ^[0-9]{1,3}?$ 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). |
national_number required | string [ 1 .. 14 ] characters ^[0-9]{1,14}?$ 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). |
{- "country_code": "str",
- "national_number": "string"
}
The phone type.
The phone type.
"FAX"
The phone information.
phone_type | string (Phone Type) The phone type. |
required | object (Phone) The phone number, in its canonical international E.164 numbering plan format. Supports only the |
{- "phone_type": "FAX",
- "phone_number": {
- "national_number": "string"
}
}
The platform or partner fee, commission, or brokerage fee that is associated with the transaction. Not a separate or isolated transaction leg from the external perspective. The platform fee is limited in scope and is always associated with the original payment for the purchase unit.
required | object (Money) The fee for this transaction. |
object (payee_base) The recipient of the fee for this transaction. If you omit this value, the default is the API caller. |
{- "amount": {
- "currency_code": "str",
- "value": "string"
}, - "payee": {
- "email_address": "string",
- "merchant_id": "stringstrings"
}
}
The platform or partner fee, commission, or brokerage fee that is associated with the transaction. Not a separate or isolated transaction leg from the external perspective. The platform fee is limited in scope and is always associated with the original payment for the purchase unit.
required | object (Money) The fee for this transaction. |
{- "amount": {
- "currency_code": "str",
- "value": "string"
}
}
The API caller-provided information about the store.
store_id | string [ 1 .. 50 ] characters ^[A-Za-z0-9-]{1,50}$ The API caller-provided external store identification number. |
terminal_id | string [ 1 .. 50 ] characters ^[A-Za-z0-9-]{1,50}$ The API caller-provided external terminal identification number. |
{- "store_id": "string",
- "terminal_id": "string"
}
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
address_line_1 | string <= 300 characters The first line of the address, such as number and street, for example, |
address_line_2 | string <= 300 characters The second line of the address, for example, a suite or apartment number. |
admin_area_2 | string <= 120 characters A city, town, or village. Smaller than |
admin_area_1 | string <= 300 characters The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example,
|
postal_code | string <= 60 characters The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. |
country_code required | string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$ The 2-character ISO 3166-1 code that identifies the country or region. Note: The country code for Great Britain is |
{- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
address_line_1 | string <= 300 characters The first line of the address, such as number and street, for example, |
address_line_2 | string <= 300 characters The second line of the address, for example, a suite or apartment number. |
admin_area_2 | string <= 120 characters A city, town, or village. Smaller than |
admin_area_1 | string <= 300 characters The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example,
|
postal_code | string <= 60 characters The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. |
country_code required | string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$ The 2-character ISO 3166-1 code that identifies the country or region. Note: The country code for Great Britain is |
{- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
address_line_1 | string <= 300 characters The first line of the address, such as number and street, for example, |
address_line_2 | string <= 300 characters The second line of the address, for example, a suite or apartment number. |
admin_area_2 | string <= 120 characters A city, town, or village. Smaller than |
admin_area_1 | string <= 300 characters The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example,
|
postal_code | string <= 60 characters The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. |
country_code required | string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$ The 2-character ISO 3166-1 code that identifies the country or region. Note: The country code for Great Britain is |
{- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
address_line_1 | string <= 300 characters The first line of the address, such as number and street, for example, |
address_line_2 | string <= 300 characters The second line of the address, for example, a suite or apartment number. |
admin_area_2 | string <= 120 characters A city, town, or village. Smaller than |
admin_area_1 | string <= 300 characters The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example,
|
postal_code | string <= 60 characters The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. |
country_code required | string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$ The 2-character ISO 3166-1 code that identifies the country or region. Note: The country code for Great Britain is |
{- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
address_line_1 | string <= 300 characters The first line of the address, such as number and street, for example, |
address_line_2 | string <= 300 characters The second line of the address, for example, a suite or apartment number. |
admin_area_2 | string <= 120 characters A city, town, or village. Smaller than |
admin_area_1 | string <= 300 characters The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example,
|
postal_code | string <= 60 characters The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. |
country_code required | string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$ The 2-character ISO 3166-1 code that identifies the country or region. Note: The country code for Great Britain is |
{- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
address_line_1 | string <= 300 characters The first line of the address, such as number and street, for example, |
address_line_2 | string <= 300 characters The second line of the address, for example, a suite or apartment number. |
admin_area_2 | string <= 120 characters A city, town, or village. Smaller than |
admin_area_1 | string <= 300 characters The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example,
|
postal_code | string <= 60 characters The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. |
country_code required | string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$ The 2-character ISO 3166-1 code that identifies the country or region. Note: The country code for Great Britain is |
{- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
address_line_1 | string <= 300 characters The first line of the address, such as number and street, for example, |
address_line_2 | string <= 300 characters The second line of the address, for example, a suite or apartment number. |
admin_area_2 | string <= 120 characters A city, town, or village. Smaller than |
admin_area_1 | string <= 300 characters The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example,
|
postal_code | string <= 60 characters The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. |
country_code required | string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$ The 2-character ISO 3166-1 code that identifies the country or region. Note: The country code for Great Britain is |
{- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
address_line_1 | string <= 300 characters The first line of the address, such as number and street, for example, |
address_line_2 | string <= 300 characters The second line of the address, for example, a suite or apartment number. |
admin_area_2 | string <= 120 characters A city, town, or village. Smaller than |
admin_area_1 | string <= 300 characters The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example,
|
postal_code | string <= 60 characters The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. |
country_code required | string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$ The 2-character ISO 3166-1 code that identifies the country or region. Note: The country code for Great Britain is |
{- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
Preferences of merchant/partner consuming the API.
include_account_details | boolean Default: "false" If this value is set to true, response will include confirmation if the customer has PayPal and/or Venmo accounts if they are eligible payment methods. Value defaults to false. |
include_vault_tokens | boolean Default: "false" If this value is set to true, response will include vaulted token information if the eligible funding source has any instrument vaulted for the customer. Value defaults to false. |
object (Payment Source Constraint) Payment source constraint defines the payment methods that needs to be included/excluded for eligibility assessment. If not passed, all payment methods will be assessed for eligibility. |
{- "include_account_details": "false",
- "include_vault_tokens": "false",
- "payment_source_constraint": {
- "constraint_type": "string",
- "payment_sources": [
- "PAYPAL"
]
}
}
The processor response information for payment requests, such as direct credit card transactions.
avs_code | string The address verification code for Visa, Discover, Mastercard, or American Express transactions.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cvv_code | string The card verification value code for for Visa, Discover, Mastercard, or American Express.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
response_code | string Processor response code for the non-PayPal payment processor errors.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payment_advice_code | string The declined payment transactions might have payment advice codes. The card networks, like Visa and Mastercard, return payment advice codes.
|
{- "avs_code": "A",
- "cvv_code": "E",
- "response_code": "0000",
- "payment_advice_code": "01"
}
required | object (amount_with_breakdown) The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any. |
object (payee) The merchant who receives the funds and fulfills the order. The merchant is also known as the payee. |
{- "amount": {
- "currency_code": "str",
- "value": "string",
- "breakdown": {
- "item_total": {
- "currency_code": "str",
- "value": "string"
}, - "shipping": {
- "currency_code": "str",
- "value": "string"
}, - "handling": {
- "currency_code": "str",
- "value": "string"
}, - "tax_total": {
- "currency_code": "str",
- "value": "string"
}, - "insurance": {
- "currency_code": "str",
- "value": "string"
}, - "shipping_discount": {
- "currency_code": "str",
- "value": "string"
}, - "discount": {
- "currency_code": "str",
- "value": "string"
}
}
}, - "payee": {
- "email_address": "string",
- "merchant_id": "stringstrings"
}
}
Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. You can reauthorize a payment only once from days four to 29.
If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment.
A reauthorized payment itself has a new honor period of three days.
You can reauthorize an authorized payment once. The allowed amount depends on context and geography, for example in US it is up to 115% of the original authorized amount, not to exceed an increase of $75 USD.
Supports only the amount
request parameter.
Note: This request is currently not supported for Partner use cases.
object (Money) The amount to reauthorize for an authorized payment. |
{- "amount": {
- "currency_code": "str",
- "value": "string"
}
}
The refund information.
status | string (Refund Status With Details) The status of the refund.
| ||||||||||
object (refund_status_details) The details of the refund status. | |||||||||||
id | string The PayPal-generated ID for the refund. | ||||||||||
invoice_id | string 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. | ||||||||||
custom_id | string [ 1 .. 255 ] characters ^[A-Za-z0-9-_.,]*$ The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. | ||||||||||
acquirer_reference_number | string [ 1 .. 36 ] characters ^[a-zA-Z0-9]+$ Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks. | ||||||||||
note_to_payer | string The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives. | ||||||||||
object (Seller Payable Breakdown) The breakdown of the refund. | |||||||||||
Array of objects (Link Description) An array of related HATEOAS links. | |||||||||||
object (Money) The amount that the payee refunded to the payer. | |||||||||||
object (payee_base) The details associated with the merchant for this transaction. | |||||||||||
create_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction occurred, in Internet date and time format. | ||||||||||
update_time | string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|... The date and time when the transaction was last updated, in Internet date and time format. |
{- "status": "CANCELLED",
- "status_details": {
- "reason": "ECHECK"
}, - "id": "string",
- "invoice_id": "string",
- "custom_id": "string",
- "acquirer_reference_number": "string",
- "note_to_payer": "string",
- "seller_payable_breakdown": {
- "platform_fees": [
- {
- "amount": {
- "currency_code": "str",
- "value": "string"
}, - "payee": {
- "email_address": "string",
- "merchant_id": "stringstrings"
}
}
], - "net_amount_breakdown": [
- {
- "payable_amount": {
- "currency_code": "str",
- "value": "string"
}, - "converted_amount": {
- "currency_code": "str",
- "value": "string"
}, - "exchange_rate": {
- "value": "string",
- "source_currency": "str",
- "target_currency": "str"
}
}
], - "gross_amount": {
- "currency_code": "str",
- "value": "string"
}, - "paypal_fee": {
- "currency_code": "str",
- "value": "string"
}, - "paypal_fee_in_receivable_currency": {
- "currency_code": "str",
- "value": "string"
}, - "net_amount": {
- "currency_code": "str",
- "value": "string"
}, - "net_amount_in_receivable_currency": {
- "currency_code": "str",
- "value": "string"
}, - "total_refunded_amount": {
- "currency_code": "str",
- "value": "string"
}
}, - "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "amount": {
- "currency_code": "str",
- "value": "string"
}, - "payer": {
- "email_address": "string",
- "merchant_id": "stringstrings"
}, - "create_time": "stringstringstringst",
- "update_time": "stringstringstringst"
}
Refunds a captured payment, by ID. For a full refund, include an empty request body. For a partial refund, include an amount
object in the request body.
custom_id | string [ 1 .. 127 ] characters ^.*$ The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. The pattern is defined by an external party and supports Unicode. |
invoice_id | string [ 1 .. 127 ] characters ^.*$ The API caller-provided external invoice ID for this order. The pattern is defined by an external party and supports Unicode. |
note_to_payer | string [ 1 .. 255 ] characters ^.*$ The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives. The pattern is defined by an external party and supports Unicode. |
object (Money) The amount to refund. To refund a portion of the captured amount, specify an amount. If amount is not specified, an amount equal to | |
object (payment_instruction) Any additional refund instructions to be set during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability. |
{- "custom_id": "string",
- "invoice_id": "string",
- "note_to_payer": "string",
- "amount": {
- "currency_code": "str",
- "value": "string"
}, - "payment_instruction": {
- "platform_fees": [
- {
- "amount": {
- "currency_code": "str",
- "value": "string"
}
}
]
}
}
The refund status with details.
status | string (Refund Status With Details) The status of the refund.
| ||||||||||
object (refund_status_details) The details of the refund status. |
{- "status": "CANCELLED",
- "status_details": {
- "reason": "ECHECK"
}
}
The details of the refund status.
reason | string (Refund Incomplete Reason) The reason why the refund has the
|
{- "reason": "ECHECK"
}
Identifiers related to a specific resource.
order_id | string [ 1 .. 20 ] characters ^[A-Z0-9]+$ Order ID related to the resource. |
authorization_id | string [ 1 .. 20 ] characters ^[A-Z0-9]+$ Authorization ID related to the resource. |
capture_id | string [ 1 .. 20 ] characters ^[A-Z0-9]+$ Capture ID related to the resource. |
{- "order_id": "string",
- "authorization_id": "string",
- "capture_id": "string"
}
Response for PayPal.
can_be_vaulted | boolean Default: "false" Indicates if the payment method can be vaulted or not. A true value indicates the payment method can be vaulted using our vaults product. If false, vaulting is not currently supported for this payment method. |
eligible_in_paypal_network | boolean (PayPal services member indicator) Flag that indicates if the customer is in the PayPal network. This value will be included in the response if the include_account_details flag is set to "true" in the API request. |
recommended | boolean Default: "false" Indicates if the payment method is recommended or not. A true value indicates the customer is payment ready and this payment method may be presented upfront. |
recommended_priority | integer [ 1 .. 3 ] This value is included in the response when recommended is true for a payment method. It indicates the priority of recommendation for payment readiness of eligible payment methods with lowest number taking the highest precedence. |
{- "can_be_vaulted": "false",
- "eligible_in_paypal_network": true,
- "recommended": "false",
- "recommended_priority": 1
}
Response for Venmo.
can_be_vaulted | boolean Default: "false" Indicates if the payment method can be vaulted or not. A true value indicates the payment method can be vaulted using our vaults product. If false, vaulting is not currently supported for this payment method. |
eligible_in_paypal_network | boolean (PayPal services member indicator) Flag that indicates if the customer is in the PayPal network. This value will be included in the response if the include_account_details flag is set to "true" in the API request. |
recommended | boolean Default: "false" Indicates if the payment method is recommended or not. A true value indicates the customer is payment ready and this payment method may be presented upfront. |
recommended_priority | integer [ 1 .. 3 ] This value is included in the response when recommended is true for a payment method. It indicates the priority of recommendation for payment readiness of eligible payment methods with lowest number taking the highest precedence. |
{- "can_be_vaulted": "false",
- "eligible_in_paypal_network": true,
- "recommended": "false",
- "recommended_priority": 1
}
The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.
Array of objects (platform_fee) [ 0 .. 1 ] items An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment. | |
required | object (Money) The amount for this captured payment in the currency of the transaction. |
object (Money) The applicable fee for this captured payment in the currency of the transaction. | |
object (Money) The applicable fee for this captured payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'. | |
object (Money) The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed as | |
object (Money) 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 | |
object (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. |
{- "platform_fees": [
- {
- "amount": {
- "currency_code": "str",
- "value": "string"
}, - "payee": {
- "email_address": "string",
- "merchant_id": "stringstrings"
}
}
], - "gross_amount": {
- "currency_code": "str",
- "value": "string"
}, - "paypal_fee": {
- "currency_code": "str",
- "value": "string"
}, - "paypal_fee_in_receivable_currency": {
- "currency_code": "str",
- "value": "string"
}, - "net_amount": {
- "currency_code": "str",
- "value": "string"
}, - "receivable_amount": {
- "currency_code": "str",
- "value": "string"
}, - "exchange_rate": {
- "value": "string",
- "source_currency": "str",
- "target_currency": "str"
}
}
The level of protection offered as defined by PayPal Seller Protection for Merchants.
status | string (Seller Protection Status) Indicates whether the transaction is eligible for seller protection. For information, see PayPal Seller Protection for Merchants.
| ||||||||
dispute_categories | Array of strings An array of conditions that are covered for the transaction. |
{- "status": "ELIGIBLE",
- "dispute_categories": [
- "string"
]
}
The shipping details.
type | string (Fullfillment Type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either
| ||||||||||
object (Name) The name of the person to whom to ship the items. Supports only the | |||||||||||
object (Portable Postal Address (Medium-Grained)) The address of the person to whom to ship the items. Supports only the |
{- "type": "SHIPPING",
- "name": {
- "full_name": "string"
}, - "address": {
- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
}
The shipping details.
type | string (Fullfillment Type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either
| ||||||||||
Array of objects (shipping_option) [ 0 .. 10 ] items An array of shipping options that the payee or merchant offers to the payer to ship or pick up their items. | |||||||||||
object (Name) The name of the person to whom to ship the items. Supports only the | |||||||||||
object (Portable Postal Address (Medium-Grained)) The address of the person to whom to ship the items. Supports only the |
{- "type": "SHIPPING",
- "options": [
- {
- "id": "string",
- "label": "string",
- "selected": true,
- "type": "SHIPPING",
- "amount": {
- "currency_code": "str",
- "value": "string"
}
}
], - "name": {
- "full_name": "string"
}, - "address": {
- "address_line_1": "string",
- "address_line_2": "string",
- "admin_area_2": "string",
- "admin_area_1": "string",
- "postal_code": "string",
- "country_code": "st"
}
}
The options that the payee or merchant offers to the payer to ship or pick up their items.
id required | string <= 127 characters A unique ID that identifies a payer-selected shipping option. | ||||||||||
label required | string <= 127 characters A description that the payer sees, which helps them choose an appropriate shipping option. For example, | ||||||||||
selected required | boolean If the API request sets | ||||||||||
type | string (shipping_type) A classification for the method of purchase fulfillment.
| ||||||||||
object (Money) The shipping cost for the selected option. |
{- "id": "string",
- "label": "string",
- "selected": true,
- "type": "SHIPPING",
- "amount": {
- "currency_code": "str",
- "value": "string"
}
}
A classification for the method of purchase fulfillment.
A classification for the method of purchase fulfillment.
Enum: | Description |
---|---|
SHIPPING | The payer intends to receive the items at a specified address. |
PICKUP | DEPRECATED. To ensure that seller protection is correctly assigned, please use 'PICKUP_IN_STORE' or 'PICKUP_FROM_PERSON' instead. Currently, this field indicates that the payer intends to pick up the items at a specified address (ie. a store address). |
PICKUP_IN_STORE | The payer intends to pick up the item(s) from the payee's physical store. Also termed as BOPIS, "Buy Online, Pick-up in Store". Seller protection is provided with this option. |
PICKUP_FROM_PERSON | The payer intends to pick up the item(s) from the payee in person. Also termed as BOPIP, "Buy Online, Pick-up in Person". Seller protection is not available, since the payer is receiving the item from the payee in person, and can validate the item prior to payment. |
"SHIPPING"
Transaction signature status identifier.
Transaction signature status identifier.
Enum: | Description |
---|---|
YES | Indicates that the signature of the PARes has been validated successfully and the message contents can be trusted. |
NO | Indicates that the PARes could not be validated. |
"YES"
Defines how and when the payment source gets vaulted.
Defines how and when the payment source gets vaulted.
Value: | Description |
---|---|
ON_SUCCESS | Defines that the payment_source will be vaulted only when at least one authorization or capture using that payment_source is successful. |
"ON_SUCCESS"
Indicates the type of the stored payment_source payment.
Indicates the type of the stored payment_source payment.
Enum: | Description |
---|---|
ONE_TIME | One Time payment such as online purchase or donation. (e.g. Checkout with one-click). |
RECURRING | Payment which is part of a series of payments with fixed or variable amounts, following a fixed time interval. (e.g. Subscription payments). |
UNSCHEDULED | Payment which is part of a series of payments that occur on a non-fixed schedule and/or have variable amounts. (e.g. Account Topup payments). |
"ONE_TIME"
Indicates if this is a first
or subsequent
payment using a stored payment source (also referred to as stored credential or card on file).
Indicates if this is a first
or subsequent
payment using a stored payment source (also referred to as stored credential or card on file).
Enum: | Description |
---|---|
FIRST | Indicates the Initial/First payment with a payment_source that is intended to be stored upon successful processing of the payment. |
SUBSEQUENT | Indicates a payment using a stored payment_source which has been successfully used previously for a payment. |
DERIVED | Indicates that PayPal will derive the value of |
"FIRST"
The tax ID of the customer. The customer is also known as the payer. Both tax_id
and tax_id_type
are required.
tax_id required | string [ 1 .. 14 ] characters ([a-zA-Z0-9]) The customer's tax ID value. | ||||||
tax_id_type required | string [ 1 .. 14 ] characters ^[A-Z0-9_]+$ The customer's tax ID type.
|
{- "tax_id": "string",
- "tax_id_type": "BR_CPF"
}
Results of 3D Secure Authentication.
authentication_status | string (pares_status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ The outcome of the issuer's authentication.
| ||||||||||||||||||
enrollment_status | string (enrolled) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Status of authentication eligibility.
|
{- "authentication_status": "Y",
- "enrollment_status": "Y"
}
The Universal Product Code of the item.
type required | string (Universal Product Code Type) [ 1 .. 5 ] characters ^[0-9A-Z_-]+$ The Universal Product Code type.
| ||||||||||||||||
code required | string [ 6 .. 17 ] characters ^[0-9]{0,17}$ The UPC product code of the item. |
{- "type": "UPC-A",
- "code": "string"
}
Describes the URL.
Describes the URL.
Base vaulting specification. The object can be extended for specific use cases within each payment_source that supports vaulting.
store_in_vault required | string (store_in_vault_instruction) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Defines how and when the payment source gets vaulted.
|
{- "store_in_vault": "ON_SUCCESS"
}
The PayPal-generated ID for the vaulted payment source. This ID should be stored on the merchant's server so the saved payment source can be used for future transactions.
The PayPal-generated ID for the vaulted payment source. This ID should be stored on the merchant's server so the saved payment source can be used for future transactions.
"string"
Basic vault instruction specification that can be extended by specific payment sources that supports vaulting.
store_in_vault | string (store_in_vault_instruction) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Defines how and when the payment source gets vaulted.
|
{- "store_in_vault": "ON_SUCCESS"
}
Resource consolidating common request and response attributes for vaulting PayPal Wallet.
store_in_vault | string (store_in_vault_instruction) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Defines how and when the payment source gets vaulted.
| ||||
description | string [ 1 .. 128 ] characters The description displayed to PayPal consumer on the approval flow for PayPal, as well as on the PayPal payment token management experience on PayPal.com. | ||||
usage_pattern | string (PayPal Payment Token Usage Pattern) [ 1 .. 30 ] characters Expected business/pricing model for the billing agreement. | ||||
usage_type required | string (PayPal Payment Token Usage Type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ The usage type associated with the PayPal payment token. | ||||
customer_type | string (PayPal Payment Token Customer Type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Default: "CONSUMER" The customer type associated with the PayPal payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer. | ||||
permit_multiple_payment_tokens | boolean Default: false Create multiple payment tokens for the same payer, merchant/platform combination. Use this when the customer has not logged in at merchant/platform. The payment token thus generated, can then also be used to create the customer account at merchant/platform. Use this also when multiple payment tokens are required for the same payer, different customer at merchant/platform. This helps to identify customers distinctly even though they may share the same PayPal account. This only applies to PayPal payment source. |
{- "store_in_vault": "ON_SUCCESS",
- "description": "string",
- "usage_pattern": "string",
- "usage_type": "string",
- "customer_type": "CONSUMER",
- "permit_multiple_payment_tokens": false
}
The details about a saved payment source.
id | string [ 1 .. 255 ] characters The PayPal-generated ID for the saved payment source. | ||||||||
status | string (Vault Status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ The vault status.
| ||||||||
Array of objects (Link Description) [ 1 .. 10 ] items An array of request-related HATEOAS links. |
{- "id": "string",
- "status": "VAULTED",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
]
}
Resource consolidating common request and response attirbutes for vaulting Venmo Wallet.
store_in_vault required | string (store_in_vault_instruction) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Defines how and when the payment source gets vaulted.
| ||||
description | string [ 1 .. 128 ] characters ^[a-zA-Z0-9_'\-., :;\!?"]*$ The description displayed to Venmo consumer on the approval flow for Venmo, as well as on the Venmo payment token management experience on Venmo.com. | ||||
usage_pattern | string (Venmo Payment Token Usage Pattern) [ 1 .. 30 ] characters ^[0-9A-Z_]+$ Expected business/pricing model for the billing agreement. | ||||
usage_type required | string (Venmo Payment Token Usage Type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ The usage type associated with the Venmo payment token. | ||||
customer_type | string (Venmo Payment Token Customer Type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Default: "CONSUMER" The customer type associated with the Venmo payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer. | ||||
permit_multiple_payment_tokens | boolean Default: false Create multiple payment tokens for the same payer, merchant/platform combination. Use this when the customer has not logged in at merchant/platform. The payment token thus generated, can then also be used to create the customer account at merchant/platform. Use this also when multiple payment tokens are required for the same payer, different customer at merchant/platform. This helps to identify customers distinctly even though they may share the same Venmo account. |
{- "store_in_vault": "ON_SUCCESS",
- "description": "string",
- "usage_pattern": "string",
- "usage_type": "string",
- "customer_type": "CONSUMER",
- "permit_multiple_payment_tokens": false
}
Payment Token info for Venmo payment source.
user_name | string [ 1 .. 50 ] characters ^[-a-zA-Z0-9_]*$ The Venmo username, as chosen by the user. |
{- "user_name": "string"
}
Additional attributes associated with the use of this Venmo Wallet.
object (customer) The details about a customer in PayPal's system of record. | |
object (vault_Venmo_wallet_base) Attributes used to provide the instructions during vaulting of the Venmo Wallet. |
{- "customer": {
- "id": "string",
- "email_address": "string"
}, - "vault": {
- "store_in_vault": "ON_SUCCESS",
- "description": "string",
- "usage_pattern": "string",
- "usage_type": "string",
- "customer_type": "CONSUMER",
- "permit_multiple_payment_tokens": false
}
}
Customizes the buyer experience during the approval process for payment with Venmo.
Note: Partners and Marketplaces might configure shipping_preference
during partner account setup, which overrides the request values.
brand_name | string [ 1 .. 127 ] characters ^.*$ The business name of the merchant. The pattern is defined by an external party and supports Unicode. | ||||||||
shipping_preference | string [ 1 .. 24 ] characters ^[A-Z_]+$ Default: "GET_FROM_FILE" The location from which the shipping address is derived.
|
{- "brand_name": "string",
- "shipping_preference": "GET_FROM_FILE"
}