Authorize payment for order

Authorizes payment for an order. To successfully authorize payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request. A buyer can approve the order upon being redirected to the rel:approve URL that was returned in the HATEOAS links in the create order response.

Note: For error handling and troubleshooting, see Orders v2 errors.

POST /v2/checkout/orders/{id}/authorize

Authorize payment for order

cURL

curl --request POST \
  --url https://api-m.sandbox.paypal.com/v2/checkout/orders/{id}/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

200

{
  "create_time": "<string>",
  "update_time": "<string>",
  "id": "<string>",
  "payment_source": {
    "card": {
      "name": "<string>",
      "last_digits": "<string>",
      "available_networks": [],
      "authentication_result": {
        "three_d_secure": {}
      },
      "attributes": {
        "vault": {
          "id": "<string>",
          "links": [
            {
              "href": "<string>",
              "rel": "<string>"
            }
          ],
          "customer": {
            "id": "<string>",
            "email_address": "<string>",
            "phone": {
              "phone_number": {
                "national_number": "<string>"
              }
            },
            "name": {
              "given_name": "<string>",
              "surname": "<string>"
            },
            "merchant_customer_id": "<string>"
          }
        }
      },
      "from_request": {
        "expiry": "<string>",
        "last_digits": "<string>"
      },
      "expiry": "<string>",
      "bin_details": {
        "bin": "<string>",
        "issuing_bank": "<string>",
        "bin_country_code": "<string>",
        "products": [
          "<string>"
        ]
      },
      "stored_credential": {
        "usage": "DERIVED",
        "previous_network_transaction_reference": {
          "id": "<string>",
          "date": "<string>",
          "acquirer_reference_number": "<string>"
        }
      }
    },
    "paypal": {
      "email_address": "<string>",
      "account_id": "<string>",
      "name": {
        "given_name": "<string>",
        "surname": "<string>"
      },
      "phone_number": {
        "national_number": "<string>"
      },
      "birth_date": "<string>",
      "business_name": "<string>",
      "tax_info": {
        "tax_id": "<string>"
      },
      "address": {
        "country_code": "<string>",
        "address_line_1": "<string>",
        "address_line_2": "<string>",
        "admin_area_2": "<string>",
        "admin_area_1": "<string>",
        "postal_code": "<string>"
      },
      "attributes": {
        "vault": {
          "id": "<string>",
          "links": [
            {
              "href": "<string>",
              "rel": "<string>"
            }
          ],
          "customer": {
            "id": "<string>",
            "email_address": "<string>",
            "phone": {
              "phone_number": {
                "national_number": "<string>"
              }
            },
            "name": {
              "given_name": "<string>",
              "surname": "<string>"
            },
            "merchant_customer_id": "<string>"
          }
        },
        "cobranded_cards": [
          {
            "labels": [
              "<string>"
            ],
            "payee": {
              "email_address": "<string>",
              "merchant_id": "<string>"
            },
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            }
          }
        ]
      },
      "stored_credential": {
        "usage": "DERIVED"
      }
    },
    "apple_pay": {
      "id": "<string>",
      "token": "<string>",
      "name": "<string>",
      "email_address": "<string>",
      "phone_number": {
        "national_number": "<string>"
      },
      "card": {
        "name": "<string>",
        "last_digits": "<string>",
        "available_networks": [],
        "authentication_result": {
          "three_d_secure": {}
        },
        "attributes": {
          "vault": {
            "id": "<string>",
            "links": [
              {
                "href": "<string>",
                "rel": "<string>"
              }
            ],
            "customer": {
              "id": "<string>",
              "email_address": "<string>",
              "phone": {
                "phone_number": {
                  "national_number": "<string>"
                }
              },
              "name": {
                "given_name": "<string>",
                "surname": "<string>"
              },
              "merchant_customer_id": "<string>"
            }
          }
        },
        "from_request": {
          "expiry": "<string>",
          "last_digits": "<string>"
        },
        "expiry": "<string>",
        "bin_details": {
          "bin": "<string>",
          "issuing_bank": "<string>",
          "bin_country_code": "<string>",
          "products": [
            "<string>"
          ]
        },
        "stored_credential": {
          "usage": "DERIVED",
          "previous_network_transaction_reference": {
            "id": "<string>",
            "date": "<string>",
            "acquirer_reference_number": "<string>"
          }
        },
        "billing_address": {
          "country_code": "<string>",
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>"
        },
        "country_code": "<string>"
      },
      "attributes": {
        "vault": {
          "id": "<string>",
          "customer": {
            "id": "<string>",
            "name": {
              "given_name": "<string>",
              "surname": "<string>"
            }
          },
          "links": [
            {
              "href": "<string>",
              "rel": "<string>"
            }
          ]
        }
      },
      "stored_credential": {
        "usage": "DERIVED",
        "previous_network_transaction_reference": {
          "id": "<string>",
          "date": "<string>",
          "acquirer_reference_number": "<string>"
        }
      }
    },
    "google_pay": {
      "name": "<string>",
      "email_address": "<string>",
      "phone_number": {
        "country_code": "<string>",
        "national_number": "<string>"
      },
      "card": {
        "name": "<string>",
        "last_digits": "<string>",
        "billing_address": {
          "country_code": "<string>",
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>"
        },
        "authentication_result": {
          "three_d_secure": {}
        }
      }
    },
    "venmo": {
      "email_address": "<string>",
      "account_id": "<string>",
      "user_name": "<string>",
      "name": {
        "given_name": "<string>",
        "surname": "<string>"
      },
      "phone_number": {
        "national_number": "<string>"
      },
      "address": {
        "country_code": "<string>",
        "address_line_1": "<string>",
        "address_line_2": "<string>",
        "admin_area_2": "<string>",
        "admin_area_1": "<string>",
        "postal_code": "<string>"
      },
      "attributes": {
        "vault": {
          "id": "<string>",
          "customer": {
            "id": "<string>",
            "name": {
              "given_name": "<string>",
              "surname": "<string>"
            }
          },
          "links": [
            {
              "href": "<string>",
              "rel": "<string>"
            }
          ]
        }
      }
    },
    "crypto": "<unknown>"
  },
  "processing_instruction": "<unknown>",
  "payer": {
    "email_address": "<string>",
    "payer_id": "<string>",
    "name": {
      "given_name": "<string>",
      "surname": "<string>"
    },
    "phone": {
      "phone_number": {
        "national_number": "<string>"
      }
    },
    "birth_date": "<string>",
    "tax_info": {
      "tax_id": "<string>"
    },
    "address": {
      "country_code": "<string>",
      "address_line_1": "<string>",
      "address_line_2": "<string>",
      "admin_area_2": "<string>",
      "admin_area_1": "<string>",
      "postal_code": "<string>"
    }
  },
  "purchase_units": [
    {
      "reference_id": "<string>",
      "amount": {
        "currency_code": "<string>",
        "value": "<string>",
        "breakdown": {
          "item_total": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "shipping": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "handling": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "tax_total": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "insurance": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "shipping_discount": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "discount": {
            "currency_code": "<string>",
            "value": "<string>"
          }
        }
      },
      "payee": {
        "email_address": "<string>",
        "merchant_id": "<string>"
      },
      "payment_instruction": {
        "platform_fees": [
          {
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "payee": {
              "email_address": "<string>",
              "merchant_id": "<string>"
            }
          }
        ],
        "disbursement_mode": "INSTANT",
        "payee_pricing_tier_id": "<string>",
        "payee_receivable_fx_rate_id": "<string>"
      },
      "description": "<string>",
      "custom_id": "<string>",
      "invoice_id": "<string>",
      "id": "<string>",
      "soft_descriptor": "<string>",
      "items": [
        {
          "name": "<string>",
          "unit_amount": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "quantity": "<string>",
          "tax": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "description": "<string>",
          "sku": "<string>",
          "url": "<string>",
          "image_url": "<string>",
          "upc": {
            "code": "<string>"
          },
          "billing_plan": {
            "billing_cycles": [
              {
                "pricing_scheme": {
                  "price": {
                    "currency_code": "<string>",
                    "value": "<string>"
                  },
                  "reload_threshold_amount": {
                    "currency_code": "<string>",
                    "value": "<string>"
                  }
                },
                "frequency": "<unknown>",
                "total_cycles": 1,
                "sequence": 1,
                "start_date": "<string>"
              }
            ],
            "setup_fee": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "name": "<string>"
          }
        }
      ],
      "shipping": {
        "name": {
          "full_name": "<string>"
        },
        "email_address": "<string>",
        "phone_number": {
          "country_code": "<string>",
          "national_number": "<string>"
        },
        "options": [
          {
            "id": "<string>",
            "label": "<string>",
            "selected": true,
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            }
          }
        ],
        "address": {
          "country_code": "<string>",
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>"
        },
        "trackers": [
          {
            "id": "<string>",
            "items": [
              {
                "name": "<string>",
                "quantity": "<string>",
                "sku": "<string>",
                "url": "<string>",
                "image_url": "<string>",
                "upc": {
                  "code": "<string>"
                }
              }
            ],
            "links": [
              {
                "href": "<string>",
                "rel": "<string>"
              }
            ],
            "create_time": "<string>",
            "update_time": "<string>"
          }
        ]
      },
      "supplementary_data": {
        "card": {
          "level_2": {
            "invoice_id": "<string>",
            "tax_total": {
              "currency_code": "<string>",
              "value": "<string>"
            }
          },
          "level_3": {
            "shipping_amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "duty_amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "discount_amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "shipping_address": {
              "country_code": "<string>",
              "address_line_1": "<string>",
              "address_line_2": "<string>",
              "admin_area_2": "<string>",
              "admin_area_1": "<string>",
              "postal_code": "<string>"
            },
            "ships_from_postal_code": "<string>",
            "line_items": [
              {
                "name": "<string>",
                "quantity": "<string>",
                "description": "<string>",
                "sku": "<string>",
                "url": "<string>",
                "image_url": "<string>",
                "upc": {
                  "code": "<string>"
                },
                "billing_plan": {
                  "billing_cycles": [
                    {
                      "pricing_scheme": {
                        "price": {
                          "currency_code": "<string>",
                          "value": "<string>"
                        },
                        "reload_threshold_amount": {
                          "currency_code": "<string>",
                          "value": "<string>"
                        }
                      },
                      "frequency": "<unknown>",
                      "total_cycles": 1,
                      "sequence": 1,
                      "start_date": "<string>"
                    }
                  ],
                  "setup_fee": {
                    "currency_code": "<string>",
                    "value": "<string>"
                  },
                  "name": "<string>"
                },
                "unit_amount": {
                  "currency_code": "<string>",
                  "value": "<string>"
                },
                "tax": {
                  "currency_code": "<string>",
                  "value": "<string>"
                },
                "commodity_code": "<string>",
                "discount_amount": {
                  "currency_code": "<string>",
                  "value": "<string>"
                },
                "total_amount": {
                  "currency_code": "<string>",
                  "value": "<string>"
                },
                "unit_of_measure": "<string>"
              }
            ]
          }
        },
        "risk": {
          "customer": {
            "ip_address": "<string>"
          }
        }
      },
      "payments": {
        "authorizations": [
          {
            "status_details": {},
            "id": "<string>",
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "invoice_id": "<string>",
            "custom_id": "<string>",
            "network_transaction_reference": {
              "id": "<string>",
              "date": "<string>",
              "acquirer_reference_number": "<string>"
            },
            "seller_protection": {
              "dispute_categories": []
            },
            "expiration_time": "<string>",
            "links": [
              {
                "href": "<string>",
                "rel": "<string>"
              }
            ],
            "create_time": "<string>",
            "update_time": "<string>",
            "processor_response": {}
          }
        ],
        "captures": [
          {
            "status_details": {},
            "id": "<string>",
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "invoice_id": "<string>",
            "custom_id": "<string>",
            "network_transaction_reference": {
              "id": "<string>",
              "date": "<string>",
              "acquirer_reference_number": "<string>"
            },
            "seller_protection": {
              "dispute_categories": []
            },
            "final_capture": false,
            "seller_receivable_breakdown": {
              "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": {
                "source_currency": "<string>",
                "target_currency": "<string>",
                "value": "<string>"
              },
              "platform_fees": [
                {
                  "amount": {
                    "currency_code": "<string>",
                    "value": "<string>"
                  },
                  "payee": {
                    "email_address": "<string>",
                    "merchant_id": "<string>"
                  }
                }
              ]
            },
            "disbursement_mode": "INSTANT",
            "links": [
              {
                "href": "<string>",
                "rel": "<string>"
              }
            ],
            "processor_response": {},
            "create_time": "<string>",
            "update_time": "<string>"
          }
        ],
        "refunds": [
          {
            "status_details": {
              "reason": "ECHECK"
            },
            "id": "<string>",
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "invoice_id": "<string>",
            "custom_id": "<string>",
            "acquirer_reference_number": "<string>",
            "note_to_payer": "<string>",
            "seller_payable_breakdown": {
              "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>"
              },
              "net_amount_in_receivable_currency": {
                "currency_code": "<string>",
                "value": "<string>"
              },
              "platform_fees": [
                {
                  "amount": {
                    "currency_code": "<string>",
                    "value": "<string>"
                  },
                  "payee": {
                    "email_address": "<string>",
                    "merchant_id": "<string>"
                  }
                }
              ],
              "net_amount_breakdown": [
                {
                  "payable_amount": {
                    "currency_code": "<string>",
                    "value": "<string>"
                  },
                  "converted_amount": {
                    "currency_code": "<string>",
                    "value": "<string>"
                  },
                  "exchange_rate": {
                    "source_currency": "<string>",
                    "target_currency": "<string>",
                    "value": "<string>"
                  }
                }
              ],
              "total_refunded_amount": {
                "currency_code": "<string>",
                "value": "<string>"
              }
            },
            "payer": {
              "email_address": "<string>",
              "merchant_id": "<string>"
            },
            "links": [
              {
                "href": "<string>",
                "rel": "<string>"
              }
            ],
            "create_time": "<string>",
            "update_time": "<string>"
          }
        ]
      },
      "most_recent_errors": [
        "<unknown>"
      ]
    }
  ],
  "links": [
    {
      "href": "<string>",
      "rel": "<string>"
    }
  ]
}

Authorizations

Authorization · string · header · required

Oauth 2.0 authentication

Headers

PayPal-Request-Id · string

The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager. It is mandatory for all single-step create order calls (E.g. Create Order Request with payment source information like Card, PayPal.vault_id, PayPal.billing_agreement_id, etc).

Required string length: 1 - 108

Prefer · string · default: return=minimal

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.

Required string length: 1 - 25

Pattern: ^[a-zA-Z=,-]*$

PayPal-Client-Metadata-Id · string

Required string length: 1 - 36

PayPal-Auth-Assertion · string

An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.

Path Parameters

id · string · required

The ID of the order that the tracking information is associated with.

Required string length: 1 - 36

Pattern: ^[A-Z0-9]+$

Body

application/json

The authorization of an order request.

payment_source · Payment Source · object

The payment source definition.

Show child attributes

Response

200

application/json

A successful response to an idempotent request returns the HTTP 200 OK status code with a JSON response body that shows authorized payment details.

The order authorize response.

create_time · string<ppaas_date_time_v3> · read-only

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

Required string length: 20 - 64

Pattern: ^[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 · string<ppaas_date_time_v3> · read-only

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

Required string length: 20 - 64

Pattern: ^[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})$

id · string · read-only

The ID of the order.

payment_source · Payment Source Response · object

The payment source used to fund the payment.

Show child attributes

intent · enum<string>

The intent to either capture payment immediately or authorize a payment for an order after order creation.

Available options: CAPTURE, AUTHORIZE

processing_instruction · any

payer · Payer · object

The customer who approves and pays for the order. The customer is also known as the payer.

Show child attributes

purchase_units · Purchase Unit · object[]

An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant.

Required array length: 1 - 10 elements

Show child attributes

status · enum<string> · read-only

The order status.

Available options: CREATED, SAVED, APPROVED, VOIDED, COMPLETED, PAYER_ACTION_REQUIRED

Required string length: 1 - 255

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

links · Link Description · object[] · read-only

An array of request-related HATEOAS links.

Required array length: 1 - 10 elements

Show child attributes