The REST Payments API and HATEOAS

One of the key features of the PayPal REST Payments API is Hypermedia As The Engine Of Application State (HATEOAS).

HATEOAS enables you to interact with the Payments API entirely through hyperlinks. Each Payments API request returns an array of links that enable you to request more information about and further interact with Payments API resources.

HATEOAS links are contextual and contain information that is relative to a specific request.

HATEOAS building blocks

When you make an initial payment request through the REST API, the response contains a links array of HATEOAS link objects:

{
  "links": [
  {
    "href": "https://api.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY",
    "rel": "self",
    "method": "GET"
  },
  {
    "href": "https://api.paypal.com/v1/payments//cgi-bin/webscr?cmd=_express-checkout&token=EC-60385559L1062554J",
    "rel": "approval_url",
    "method": "REDIRECT"
  },
  {
    "href": "https://api.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY/execute",
    "rel": "execute",
    "method": "POST"
  }]
}

Each link object in a HATEOAS links array contains:

href The URL of the related HATEOAS link to use for subsequent calls.
rel The link relationship. Describes how this link relates to the previous call.
method The HTTP method to use to make the related call.

href

The complete target URL, or link, to use in combination with the HTTP method to make the related call.

Note: href is the key HATEOAS component that links a completed call with a subsequent call.

rel

The link relationship. Describes how the href link relates to the previous call.

The relationship is one of these values:

Relationship Use this link to
self Get information about the call itself.
For example, use the self link returned from a PayPal payment request to get more information about the payment. Or, use the self link returned from a refund request to get more information about the refund.
parent_payment Get information about the original payment.
All payment-related calls, including payments, sales, refunds, authorizations, captures, and orders, have a parent payment.
sale Show sale details.
update Execute approved PayPal payment.
authorization Show authorized payment details for a captured payment.
reauthorize Reauthorize authorized PayPal payment.
capture Capture authorized payments.
void Void an authorized payment.
refund Refund a sale.
delete Delete a stored credit card.

method

The HTTP method to use in combination with the link to make the related call.

Method Description
POST Create or manage payment resources:
GET Show details for or list these resources:
DELETE Delete a stored credit card
REDIRECT Not an HTTP method. Instead, specifies the redirect URL where payers are redirected to approve a PayPal account payment.

Additional information