Capture authorized payment

POST 
/authorizations/:authorization_id/capture

Captures an authorized payment, by ID.

Request

Path Parameters

authorization_id stringrequired

The PayPal-generated ID for the authorized payment to capture.

Header Parameters

PayPal-Request-Id string

The server stores keys for 45 days.

Prefer string
The preferred server response upon successful completion of the request. Value is:
• return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
• return=representation. The server returns a complete resource representation, including the current state of the resource.
Default value: return=minimal
Authorization stringrequired

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type stringrequired

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

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.

application/json

Body

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.

Possible values: non-empty and <= 127 characters, Value must match regular expression ^.{1,127}$

note_to_payer string

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

Possible values: non-empty and <= 255 characters, Value must match regular expression ^.{1,255}$

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

payment_instruction

object

Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order.

platform_fees

object[]

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.

Possible values: <= 1

Array [

amount

object

required

The fee for this transaction.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

payee

object

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

email_address merchant_common_email_address_v2

The email address of merchant.

Possible values: >= 3 characters and <= 254 characters, Value must match regular expression (?:[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+(?:.[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])

merchant_id ppaas_payer_id_v3

The encrypted PayPal account ID of the merchant.

Possible values: >= 13 characters and <= 13 characters, Value must match regular expression ^[2-9A-HJ-NP-Z]{13}$

]

payee_receivable_fx_rate_id string

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.

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

disbursement_mode Disbursement Mode (string)

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.

Possible values: non-empty and <= 16 characters, Value must match regular expression ^[A-Z_]+$, [INSTANT, DELAYED]

Default value: INSTANT
soft_descriptor string

The payment descriptor on the payer's account statement.

Possible values: <= 22 characters

amount

object

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.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Responses

200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows captured payment details.

application/json

Schema

Schema

object
status Capture Status (string)

The status of the captured payment.

Possible values: [COMPLETED, DECLINED, PARTIALLY_REFUNDED, PENDING, REFUNDED, FAILED]

status_details

object

The details of the captured payment status.

reason Capture Incomplete Reason (string)

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

Possible values: non-empty and <= 64 characters, Value must match regular expression ^[A-Z_]+$, [BUYER_COMPLAINT, CHARGEBACK, ECHECK, INTERNATIONAL_WITHDRAWAL, OTHER, PENDING_REVIEW, RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION, REFUNDED, TRANSACTION_APPROVED_AWAITING_FUNDING, UNILATERAL, VERIFICATION_REQUIRED, DECLINED_BY_RISK_FRAUD_FILTERS]

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

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

Possible values: <= 255 characters

final_capture boolean
Indicates whether you can make additional captures against the authorized payment. Set to true if you do not intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.
Default value: false
disbursement_mode Disbursement Mode (string)
The funds that are held on behalf of the merchant.
Possible values: non-empty and <= 16 characters, Value must match regular expression ^[A-Z_]+$, [INSTANT, DELAYED]
Default value: INSTANT

links

object[]

An array of related HATEOAS links.

Array [

href stringrequired

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

rel stringrequired

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

method string

The HTTP method required to make the related call.

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

]

amount

object

The amount for this captured payment.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

network_transaction_reference

object

Reference values used by the card network to identify a transaction.

id stringrequired

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 -.

Possible values: >= 9 characters and <= 36 characters, Value must match regular expression ^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$

date string

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.

Possible values: >= 4 characters and <= 4 characters, Value must match regular expression ^[0-9]+$

acquirer_reference_number string

Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.

Possible values: non-empty and <= 36 characters, Value must match regular expression ^[a-zA-Z0-9]+$

network Card Brand (string)

Name of the card network through which the transaction was routed.

Possible values: non-empty and <= 255 characters, Value must match regular expression ^[A-Z_]+$, [VISA, MASTERCARD, DISCOVER, AMEX, SOLO, JCB, STAR, DELTA, SWITCH, MAESTRO, CB_NATIONALE, CONFIGOGA, CONFIDIS, ELECTRON, CETELEM, CHINA_UNION_PAY, DINERS, ELO, HIPER, HIPERCARD, RUPAY, GE, SYNCHRONY, EFTPOS, UNKNOWN]

seller_protection

object

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

status Seller Protection Status (string)

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

Possible values: [ELIGIBLE, PARTIALLY_ELIGIBLE, NOT_ELIGIBLE]

dispute_categories string[]

An array of conditions that are covered for the transaction.

Possible values: [ITEM_NOT_RECEIVED, UNAUTHORIZED_TRANSACTION]

seller_receivable_breakdown

object

The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.

platform_fees

object[]

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

Possible values: <= 1

Array [

amount

object

required

The fee for this transaction.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

payee

object

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

email_address merchant_common_email_address_v2

The email address of merchant.

Possible values: >= 3 characters and <= 254 characters, Value must match regular expression (?:[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+(?:.[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])

merchant_id ppaas_payer_id_v3

The encrypted PayPal account ID of the merchant.

Possible values: >= 13 characters and <= 13 characters, Value must match regular expression ^[2-9A-HJ-NP-Z]{13}$

]

gross_amount

object

required

The amount for this captured payment in the currency of the transaction.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

paypal_fee

object

The applicable fee for this captured payment in the currency of the transaction.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

paypal_fee_in_receivable_currency

object

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'.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

net_amount

object

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

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

receivable_amount

object

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

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

exchange_rate

object

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.

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 ppaas_common_currency_code_v2

The source currency from which to convert an amount.

Possible values: >= 3 characters and <= 3 characters

target_currency ppaas_common_currency_code_v2

The target currency to which to convert an amount.

Possible values: >= 3 characters and <= 3 characters

processor_response

object

An object that provides additional processor information for a direct credit card transaction.

avs_code string

The address verification code for Visa, Discover, Mastercard, or American Express transactions.

Possible values: [A, B, C, D, E, F, G, I, M, N, P, R, S, U, W, X, Y, Z, Null, 0, 1, 2, 3, 4]

cvv_code string

The card verification value code for for Visa, Discover, Mastercard, or American Express.

Possible values: [E, I, M, N, P, S, U, X, All others, 0, 1, 2, 3, 4]

response_code string

Processor response code for the non-PayPal payment processor errors.

Possible values: [0000, 00N7, 0100, 0390, 0500, 0580, 0800, 0880, 0890, 0960, 0R00, 1000, 10BR, 1300, 1310, 1312, 1317, 1320, 1330, 1335, 1340, 1350, 1352, 1360, 1370, 1380, 1382, 1384, 1390, 1393, 5100, 5110, 5120, 5130, 5135, 5140, 5150, 5160, 5170, 5180, 5190, 5200, 5210, 5400, 5500, 5650, 5700, 5710, 5800, 5900, 5910, 5920, 5930, 5950, 6300, 7600, 7700, 7710, 7800, 7900, 8000, 8010, 8020, 8030, 8100, 8110, 8220, 9100, 9500, 9510, 9520, 9530, 9540, 9600, PCNR, PCVV, PP06, PPRN, PPAD, PPAB, PPAE, PPAG, PPAI, PPAR, PPAU, PPAV, PPAX, PPBG, PPC2, PPCE, PPCO, PPCR, PPCT, PPCU, PPD3, PPDC, PPDI, PPDV, PPDT, PPEF, PPEL, PPER, PPEX, PPFE, PPFI, PPFR, PPFV, PPGR, PPH1, PPIF, PPII, PPIM, PPIT, PPLR, PPLS, PPMB, PPMC, PPMD, PPNC, PPNL, PPNM, PPNT, PPPH, PPPI, PPPM, PPQC, PPRE, PPRF, PPRR, PPS0, PPS1, PPS2, PPS3, PPS4, PPS5, PPS6, PPSC, PPSD, PPSE, PPTE, PPTF, PPTI, PPTR, PPTT, PPTV, PPUA, PPUC, PPUE, PPUI, PPUP, PPUR, PPVC, PPVE, PPVT]

payment_advice_code string

The declined payment transactions might have payment advice codes. The card networks, like Visa and Mastercard, return payment advice codes.

Possible values: [01, 02, 03, 21]

create_time ppaas_date_time_v3

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

Possible values: >= 20 characters and <= 64 characters, Value must match regular expression ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$

update_time ppaas_date_time_v3

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

Possible values: >= 20 characters and <= 64 characters, Value must match regular expression ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$

supplementary_data

object

An object that provides supplementary/additional data related to a payment transaction.

related_ids

object

Identifiers related to a specific resource.

order_id string

Order ID related to the resource.

Possible values: non-empty and <= 20 characters, Value must match regular expression ^[A-Z0-9]+$

authorization_id string

Authorization ID related to the resource.

Possible values: non-empty and <= 20 characters, Value must match regular expression ^[A-Z0-9]+$

capture_id string

Capture ID related to the resource.

Possible values: non-empty and <= 20 characters, Value must match regular expression ^[A-Z0-9]+$

payee

object

The details associated with the merchant for this transaction.

email_address merchant_common_email_address_v2

The email address of merchant.

Possible values: >= 3 characters and <= 254 characters, Value must match regular expression (?:[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+(?:.[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])

merchant_id ppaas_payer_id_v3

The encrypted PayPal account ID of the merchant.

Possible values: >= 13 characters and <= 13 characters, Value must match regular expression ^[2-9A-HJ-NP-Z]{13}$

Example (from schema)

{
  "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": "string",
    "value": "string"
  },
  "network_transaction_reference": {
    "id": "string",
    "date": "string",
    "acquirer_reference_number": "string",
    "network": "VISA"
  },
  "seller_protection": {
    "status": "ELIGIBLE",
    "dispute_categories": [
      "ITEM_NOT_RECEIVED"
    ]
  },
  "seller_receivable_breakdown": {
    "platform_fees": [
      {
        "amount": {
          "currency_code": "string",
          "value": "string"
        },
        "payee": {
          "email_address": "string",
          "merchant_id": "string"
        }
      }
    ],
    "gross_amount": {
      "currency_code": "string",
      "value": "string"
    },
    "paypal_fee": {
      "currency_code": "string",
      "value": "string"
    },
    "paypal_fee_in_receivable_currency": {
      "currency_code": "string",
      "value": "string"
    },
    "net_amount": {
      "currency_code": "string",
      "value": "string"
    },
    "receivable_amount": {
      "currency_code": "string",
      "value": "string"
    },
    "exchange_rate": {
      "value": "string",
      "source_currency": "string",
      "target_currency": "string"
    }
  },
  "processor_response": {
    "avs_code": "A",
    "cvv_code": "E",
    "response_code": "0000",
    "payment_advice_code": "01"
  },
  "create_time": "string",
  "update_time": "string",
  "supplementary_data": {
    "related_ids": {
      "order_id": "string",
      "authorization_id": "string",
      "capture_id": "string"
    }
  },
  "payee": {
    "email_address": "string",
    "merchant_id": "string"
  }
}

201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows captured payment details.

application/json

Schema

Schema

object
status Capture Status (string)

The status of the captured payment.

Possible values: [COMPLETED, DECLINED, PARTIALLY_REFUNDED, PENDING, REFUNDED, FAILED]

status_details

object

The details of the captured payment status.

reason Capture Incomplete Reason (string)

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

Possible values: non-empty and <= 64 characters, Value must match regular expression ^[A-Z_]+$, [BUYER_COMPLAINT, CHARGEBACK, ECHECK, INTERNATIONAL_WITHDRAWAL, OTHER, PENDING_REVIEW, RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION, REFUNDED, TRANSACTION_APPROVED_AWAITING_FUNDING, UNILATERAL, VERIFICATION_REQUIRED, DECLINED_BY_RISK_FRAUD_FILTERS]

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

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

Possible values: <= 255 characters

final_capture boolean
Indicates whether you can make additional captures against the authorized payment. Set to true if you do not intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.
Default value: false
disbursement_mode Disbursement Mode (string)
The funds that are held on behalf of the merchant.
Possible values: non-empty and <= 16 characters, Value must match regular expression ^[A-Z_]+$, [INSTANT, DELAYED]
Default value: INSTANT

links

object[]

An array of related HATEOAS links.

Array [

href stringrequired

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

rel stringrequired

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

method string

The HTTP method required to make the related call.

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

]

amount

object

The amount for this captured payment.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

network_transaction_reference

object

Reference values used by the card network to identify a transaction.

id stringrequired

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 -.

Possible values: >= 9 characters and <= 36 characters, Value must match regular expression ^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$

date string

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.

Possible values: >= 4 characters and <= 4 characters, Value must match regular expression ^[0-9]+$

acquirer_reference_number string

Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.

Possible values: non-empty and <= 36 characters, Value must match regular expression ^[a-zA-Z0-9]+$

network Card Brand (string)

Name of the card network through which the transaction was routed.

Possible values: non-empty and <= 255 characters, Value must match regular expression ^[A-Z_]+$, [VISA, MASTERCARD, DISCOVER, AMEX, SOLO, JCB, STAR, DELTA, SWITCH, MAESTRO, CB_NATIONALE, CONFIGOGA, CONFIDIS, ELECTRON, CETELEM, CHINA_UNION_PAY, DINERS, ELO, HIPER, HIPERCARD, RUPAY, GE, SYNCHRONY, EFTPOS, UNKNOWN]

seller_protection

object

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

status Seller Protection Status (string)

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

Possible values: [ELIGIBLE, PARTIALLY_ELIGIBLE, NOT_ELIGIBLE]

dispute_categories string[]

An array of conditions that are covered for the transaction.

Possible values: [ITEM_NOT_RECEIVED, UNAUTHORIZED_TRANSACTION]

seller_receivable_breakdown

object

The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.

platform_fees

object[]

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

Possible values: <= 1

Array [

amount

object

required

The fee for this transaction.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

payee

object

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

email_address merchant_common_email_address_v2

The email address of merchant.

Possible values: >= 3 characters and <= 254 characters, Value must match regular expression (?:[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+(?:.[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])

merchant_id ppaas_payer_id_v3

The encrypted PayPal account ID of the merchant.

Possible values: >= 13 characters and <= 13 characters, Value must match regular expression ^[2-9A-HJ-NP-Z]{13}$

]

gross_amount

object

required

The amount for this captured payment in the currency of the transaction.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

paypal_fee

object

The applicable fee for this captured payment in the currency of the transaction.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

paypal_fee_in_receivable_currency

object

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'.

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

net_amount

object

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

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

receivable_amount

object

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

currency_code ppaas_common_currency_code_v2required

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

Possible values: >= 3 characters and <= 3 characters

value stringrequired

The value, which might be:

• An integer for currencies like JPY that are not typically fractional.
• A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

exchange_rate

object

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.

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 ppaas_common_currency_code_v2

The source currency from which to convert an amount.

Possible values: >= 3 characters and <= 3 characters

target_currency ppaas_common_currency_code_v2

The target currency to which to convert an amount.

Possible values: >= 3 characters and <= 3 characters

processor_response

object

An object that provides additional processor information for a direct credit card transaction.

avs_code string

The address verification code for Visa, Discover, Mastercard, or American Express transactions.

Possible values: [A, B, C, D, E, F, G, I, M, N, P, R, S, U, W, X, Y, Z, Null, 0, 1, 2, 3, 4]

cvv_code string

The card verification value code for for Visa, Discover, Mastercard, or American Express.

Possible values: [E, I, M, N, P, S, U, X, All others, 0, 1, 2, 3, 4]

response_code string

Processor response code for the non-PayPal payment processor errors.

Possible values: [0000, 00N7, 0100, 0390, 0500, 0580, 0800, 0880, 0890, 0960, 0R00, 1000, 10BR, 1300, 1310, 1312, 1317, 1320, 1330, 1335, 1340, 1350, 1352, 1360, 1370, 1380, 1382, 1384, 1390, 1393, 5100, 5110, 5120, 5130, 5135, 5140, 5150, 5160, 5170, 5180, 5190, 5200, 5210, 5400, 5500, 5650, 5700, 5710, 5800, 5900, 5910, 5920, 5930, 5950, 6300, 7600, 7700, 7710, 7800, 7900, 8000, 8010, 8020, 8030, 8100, 8110, 8220, 9100, 9500, 9510, 9520, 9530, 9540, 9600, PCNR, PCVV, PP06, PPRN, PPAD, PPAB, PPAE, PPAG, PPAI, PPAR, PPAU, PPAV, PPAX, PPBG, PPC2, PPCE, PPCO, PPCR, PPCT, PPCU, PPD3, PPDC, PPDI, PPDV, PPDT, PPEF, PPEL, PPER, PPEX, PPFE, PPFI, PPFR, PPFV, PPGR, PPH1, PPIF, PPII, PPIM, PPIT, PPLR, PPLS, PPMB, PPMC, PPMD, PPNC, PPNL, PPNM, PPNT, PPPH, PPPI, PPPM, PPQC, PPRE, PPRF, PPRR, PPS0, PPS1, PPS2, PPS3, PPS4, PPS5, PPS6, PPSC, PPSD, PPSE, PPTE, PPTF, PPTI, PPTR, PPTT, PPTV, PPUA, PPUC, PPUE, PPUI, PPUP, PPUR, PPVC, PPVE, PPVT]

payment_advice_code string

The declined payment transactions might have payment advice codes. The card networks, like Visa and Mastercard, return payment advice codes.

Possible values: [01, 02, 03, 21]

create_time ppaas_date_time_v3

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

Possible values: >= 20 characters and <= 64 characters, Value must match regular expression ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$

update_time ppaas_date_time_v3

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

Possible values: >= 20 characters and <= 64 characters, Value must match regular expression ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$

supplementary_data

object

An object that provides supplementary/additional data related to a payment transaction.

related_ids

object

Identifiers related to a specific resource.

order_id string

Order ID related to the resource.

Possible values: non-empty and <= 20 characters, Value must match regular expression ^[A-Z0-9]+$

authorization_id string

Authorization ID related to the resource.

Possible values: non-empty and <= 20 characters, Value must match regular expression ^[A-Z0-9]+$

capture_id string

Capture ID related to the resource.

Possible values: non-empty and <= 20 characters, Value must match regular expression ^[A-Z0-9]+$

payee

object

The details associated with the merchant for this transaction.

email_address merchant_common_email_address_v2

The email address of merchant.

Possible values: >= 3 characters and <= 254 characters, Value must match regular expression (?:[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+(?:.[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])

merchant_id ppaas_payer_id_v3

The encrypted PayPal account ID of the merchant.

Possible values: >= 13 characters and <= 13 characters, Value must match regular expression ^[2-9A-HJ-NP-Z]{13}$

Example (from schema)

{
  "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": "string",
    "value": "string"
  },
  "network_transaction_reference": {
    "id": "string",
    "date": "string",
    "acquirer_reference_number": "string",
    "network": "VISA"
  },
  "seller_protection": {
    "status": "ELIGIBLE",
    "dispute_categories": [
      "ITEM_NOT_RECEIVED"
    ]
  },
  "seller_receivable_breakdown": {
    "platform_fees": [
      {
        "amount": {
          "currency_code": "string",
          "value": "string"
        },
        "payee": {
          "email_address": "string",
          "merchant_id": "string"
        }
      }
    ],
    "gross_amount": {
      "currency_code": "string",
      "value": "string"
    },
    "paypal_fee": {
      "currency_code": "string",
      "value": "string"
    },
    "paypal_fee_in_receivable_currency": {
      "currency_code": "string",
      "value": "string"
    },
    "net_amount": {
      "currency_code": "string",
      "value": "string"
    },
    "receivable_amount": {
      "currency_code": "string",
      "value": "string"
    },
    "exchange_rate": {
      "value": "string",
      "source_currency": "string",
      "target_currency": "string"
    }
  },
  "processor_response": {
    "avs_code": "A",
    "cvv_code": "E",
    "response_code": "0000",
    "payment_advice_code": "01"
  },
  "create_time": "string",
  "update_time": "string",
  "supplementary_data": {
    "related_ids": {
      "order_id": "string",
      "authorization_id": "string",
      "capture_id": "string"
    }
  },
  "payee": {
    "email_address": "string",
    "merchant_id": "string"
  }
}

400

The request failed because it is not well-formed or is syntactically incorrect or violates schema.

application/json

Schema

Schema

name stringrequired

The human-readable, unique name of the error.

message stringrequired

The message that describes the error.

debug_id stringrequired

The PayPal internal ID. Used for correlation purposes.

details object[]

An array of additional details about the error.

links object[]

An array of request-related HATEOAS links.

Example (from schema)

{
  "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"
    }
  ]
}

401

Authentication failed due to missing authorization header, or invalid authentication credentials.

application/json

Schema

Schema

name stringrequired

The human-readable, unique name of the error.

message stringrequired

The message that describes the error.

debug_id stringrequired

The PayPal internal ID. Used for correlation purposes.

details object[]

An array of additional details about the error.

links object[]

An array of request-related HATEOAS links.

Example (from schema)

{
  "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"
    }
  ]
}

403

The request failed because the caller has insufficient permissions.

application/json

Schema

Schema

name stringrequired

The human-readable, unique name of the error.

message stringrequired

The message that describes the error.

debug_id stringrequired

The PayPal internal ID. Used for correlation purposes.

details object[]

An array of additional details about the error.

links object[]

An array of request-related HATEOAS links.

Example (from schema)

{
  "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"
    }
  ]
}

404

The request failed because the resource does not exist.

application/json

Schema

Schema

name stringrequired

The human-readable, unique name of the error.

message stringrequired

The message that describes the error.

debug_id stringrequired

The PayPal internal ID. Used for correlation purposes.

details object[]

An array of additional details about the error.

links object[]

An array of request-related HATEOAS links.

Example (from schema)

{
  "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"
    }
  ]
}

409

The server has detected a conflict while processing this request.

application/json

Schema

Schema

name stringrequired

The human-readable, unique name of the error.

message stringrequired

The message that describes the error.

debug_id stringrequired

The PayPal internal ID. Used for correlation purposes.

details object[]

An array of additional details about the error.

links object[]

An array of request-related HATEOAS links.

Example (from schema)

{
  "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"
    }
  ]
}

422

The request failed because it is semantically incorrect or failed business validation.

application/json

Schema

Schema

name stringrequired

The human-readable, unique name of the error.

message stringrequired

The message that describes the error.

debug_id stringrequired

The PayPal internal ID. Used for correlation purposes.

details object[]

An array of additional details about the error.

links object[]

An array of request-related HATEOAS links.

Example (from schema)

{
  "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"
    }
  ]
}

500

The request failed because an internal server error occurred.

default

The error response.

application/json

Schema

Schema

name stringrequired

The human-readable, unique name of the error.

message stringrequired

The message that describes the error.

debug_id stringrequired

The PayPal internal ID. Used for correlation purposes.

details object[]

An array of additional details about the error.

links object[]

An array of request-related HATEOAS links.

Example (from schema)

{
  "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"
    }
  ]
}

Loading...