API Reference

Paypal Payments

PayPal payments can be created and associated to an order in a few steps:

  1. Create a Paypal payment, passing a valid return url and cancel url
  2. Get the approval url from the response
  3. Redirect the customer to the approval url
  4. Get the Payer ID from the return url parameters
  5. Update the Paypal payment with the Payer ID
PayPal payments are one-time payment sources and cannot be saved in customer wallets.

The paypal payment object

A paypal payment object is returned as part of the response body of each successful create, list, retrieve or update API call. The following table contains the list of all its fields along with their type, description and example values.
Object fields:
return_url
string
The URL where the payer is redirected after they approve the payment.
Example:
https://yourbrand.com/thankyou
cancel_url
string
The URL where the payer is redirected after they cancel the payment.
Example:
https://yourbrand.com/checkout/payment
note_to_payer
string
A free-form field that you can use to send a note to the payer on PayPal.
Example:
Thank you for shopping with us!
paypal_payer_id
string
The id of the payer that PayPal passes in the return_url.
Example:
ABCDEFG123456
name
string
The PayPal payer id (if present)
Example:
ABCDEFG123456
paypal_id
string
The id of the PayPal payment object.
Example:
1234567890
status
string
The PayPal payment status. One of 'created' (default) or 'approved'.
Example:
created
approval_url
string
The URL the customer should be redirected to approve the payment.
Example:
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-1234567890ABCDEFG
id
integer
Unique identifier for the resource.
Example:
1234
created_at
datetime
Time at which the resource was created.
Example:
2018-01-01T12:00:00.000Z
updated_at
datetime
Time at which the resource was last updated.
Example:
2018-01-01T12:00:00.000Z
reference
string
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
object
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example: 
{"foo":"bar"}
order
relationship (N:1)
The order associated to the paypal payment, that is set as its payment source.

Create a paypal payment

To create a new paypal payment, send a POST request to the /api/paypal_payments endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.
Arguments:
return_url
required
The URL where the payer is redirected after they approve the payment.
Example:
https://yourbrand.com/thankyou
cancel_url
required
The URL where the payer is redirected after they cancel the payment.
Example:
https://yourbrand.com/checkout/payment
note_to_payer
optional
A free-form field that you can use to send a note to the payer on PayPal.
Example:
Thank you for shopping with us!
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
#
order
required
The order associated to the paypal payment, that is set as its payment source.
Example request:
POST /api/paypal_payments HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "paypal_payments",
    "attributes": {
      "return_url": "https://yourbrand.com/thankyou",
      "cancel_url": "https://yourbrand.com/checkout/payment"
    },
    "relationships": {
      "order": {
        "data": {
          "type": "orders",
          "id": "1234"
        }
      }
    }
  }
}
Example response: 201 Created
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "paypal_payments",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/paypal_payments/1234"
    },
    "attributes": {
      "return_url": "https://yourbrand.com/thankyou",
      "cancel_url": "https://yourbrand.com/checkout/payment",
      "note_to_payer": "Thank you for shopping with us!",
      "paypal_payer_id": "ABCDEFG123456",
      "name": "ABCDEFG123456",
      "paypal_id": "1234567890",
      "status": "created",
      "approval_url": "https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-1234567890ABCDEFG",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "order": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/paypal_payments/1234/relationships/order",
          "related": "https://your-brand.commercelayer.io/api/paypal_payments/1234/order"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

List all paypal payments

To fetch a collection of paypal payments, send a GET request to the /api/paypal_payments endpoint.

Example request:
GET /api/paypal_payments HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "1234",
      "type": "paypal_payments",
      "links": {
        "self": "https://your-brand.commercelayer.io/api/paypal_payments/1234"
      },
      "attributes": {
        "return_url": "https://yourbrand.com/thankyou",
        "cancel_url": "https://yourbrand.com/checkout/payment",
        "note_to_payer": "Thank you for shopping with us!",
        "paypal_payer_id": "ABCDEFG123456",
        "name": "ABCDEFG123456",
        "paypal_id": "1234567890",
        "status": "created",
        "approval_url": "https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-1234567890ABCDEFG",
        "id": "1234",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "ANYREFEFERNCE",
        "metadata": {
          "foo": "bar"
        }
      },
      "relationships": {
        "order": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/paypal_payments/1234/relationships/order",
            "related": "https://your-brand.commercelayer.io/api/paypal_payments/1234/order"
          }
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "other": "... 24 paypal_payments (first page)"
    }
  ],
  "meta": {
    "record_count": 125,
    "page_count": 5
  },
  "links": {
    "first": "/api/paypal_payments?page[number]=1&page[size]=25",
    "prev": "/api/paypal_payments?page[number]=2&page[size]=25",
    "next": "/api/paypal_payments?page[number]=4&page[size]=25",
    "last": "/api/paypal_payments?page[number]=5&page[size]=25"
  }
}
Available filters
idqreferenceidscreated_at_fromcreated_at_toupdated_at_fromupdated_at_to
Sortable attributes
idcreated_atupdated_atreference

Retrieve a paypal payment

To fetch a single paypal payment, send a GET request to the /api/paypal_payments/{{id}} endpoint, where {{id}} is the id of the resource that you want to retrieve.
Example request:
GET /api/paypal_payments/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "paypal_payments",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/paypal_payments/1234"
    },
    "attributes": {
      "return_url": "https://yourbrand.com/thankyou",
      "cancel_url": "https://yourbrand.com/checkout/payment",
      "note_to_payer": "Thank you for shopping with us!",
      "paypal_payer_id": "ABCDEFG123456",
      "name": "ABCDEFG123456",
      "paypal_id": "1234567890",
      "status": "created",
      "approval_url": "https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-1234567890ABCDEFG",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "order": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/paypal_payments/1234/relationships/order",
          "related": "https://your-brand.commercelayer.io/api/paypal_payments/1234/order"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Update a paypal payment

To update an existing paypal payment, send a PATCH request to the /api/paypal_payments/{{id}} endpoint, where {{id}} is the id of the resource that you want to update. The following table contains the list of all the possible arguments that you can pass with the request body, along with their type, description and examples values. Please note that all arguments are optional.
Arguments:
paypal_payer_id
optional
The id of the payer that PayPal passes in the return_url.
Example:
ABCDEFG123456
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
#
order
optional
The order associated to the paypal payment, that is set as its payment source.
Example request:
PATCH /api/paypal_payments/1234 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "paypal_payments",
    "id": 1234,
    "attributes": {
      "paypal_payer_id": "ABCDEFG123456"
    },
    "relationships": {
    }
  }
}
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "paypal_payments",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/paypal_payments/1234"
    },
    "attributes": {
      "return_url": "https://yourbrand.com/thankyou",
      "cancel_url": "https://yourbrand.com/checkout/payment",
      "note_to_payer": "Thank you for shopping with us!",
      "paypal_payer_id": "ABCDEFG123456",
      "name": "ABCDEFG123456",
      "paypal_id": "1234567890",
      "status": "created",
      "approval_url": "https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-1234567890ABCDEFG",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "order": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/paypal_payments/1234/relationships/order",
          "related": "https://your-brand.commercelayer.io/api/paypal_payments/1234/order"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Delete a paypal payment

To delete a paypal payment, send a DELETE request to the /api/paypal_payments/{{id}} endpoint, where {{id}} is the id of the resource that you want to delete.
Example request:
DELETE /api/paypal_payments/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 204 No Content
HTTP/1.1 204 No Content

API Schema

Get our machine-readable JSON schema that follows the OpenAPI Specification (formerly Swagger).

Run in Postman

Get our Postman collection in one click and start making real calls to Commerce Layer API in minutes.

Need help?

Get in touch with our support team if you have any questions or want to learn more about Commerce Layer.