NAV Navbar
shell
  • Introduction
  • Api Client
  • Authentication
  • Resource identifier
  • Errors
  • Users
  • Webhooks
  • Contracts
  • Retry payment
  • Clauses
  • Payments
  • Customers
  • Subscriptions
  • Amendment
  • Introduction

    Welcome to the Pagaio API!

    The API follow the JSON-API specification, you can read this specification to understand each request body structure.

    Api Client

    PHP

    You will find the php api client on our github account : https://github.com/pagaio-lab/api-php-client/

    Authentication

    To authorize, use this code:

    # With shell, you can just pass the correct header with each request
    curl "api_endpoint_here"
      --header "Authorization: Bearer your_api_token"
    

    Make sure to replace your_api_token with your API key.

    Pagaio uses API keys to allow access to the API. An API key determine if you use Pagaio in live or test mode. Two API Keys are linked to your account. One in live mode and the other one in test mode.

    Pagaio expects for the API key to be included in all API requests to the server in a header that looks like the following:

    Authorization: Bearer your_api_token

    Resource identifier

    All resources in the application have a unique identifier. We use a UUID (version 4) to identify every resource.

    When you create a new resource, you are able to provide this identifier or you can choose to not generate it and the server will do it for you. In the first case you already know the identifier and in the second case you will have to retrieve in the response.

    The resource identifier, on a POST request is always at path data.id. If you decide to not provide it, remove this path.

    Errors

    Following error code are used by the API :

    Error Code Meaning
    400 Bad Request -- an error occurs with your request parameters. You will have more info in the response body.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- You can't access to this resource.
    404 Not Found -- The resource is not found.
    405 Method Not Allowed
    409 Resource Conflict -- a resource with the same identifer already exists. Try with a different one.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

    Users

    /me

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/me'
    

    This request will return

    {
        "live_mode": false,
        "account": {
            "id": "7dd3f427-fb85-4224-b04d-4bb4cb75ecb9",
            "subdomain": "pagaio",
            "company": "pagaio",
            "created_at": "2017-08-05T08:35:46+00:00"
        }
    }
    

    This endpoint will return information linked with the token used in the Authorization header. You will know if the token is a live or test token and the account information linked to him.

    HTTP request

    GET https://api.pagaio.com/me

    Webhooks

    Using webhooks

    Responding to a webhook

    A webhook is a request against a endpoint you define. When a request is sent to this endpoint you must return a valid HTTP status code. If everything is ok, return a 2xx status code.

    If you return something else than a 2xx status code, the same webhook will be retry later 3 times. The first time 5 minutes after, then 10 minutes and then 15 minutes. For each retry, if you return a 2xx the next attempt will not be retried.

    webhook signature

    Verify a signature in php

    $payload = @file_get_contents('php://input');
    $receivedSignature = $_SERVER["HTTP_PAGAIO_SIGNATURE"];
    
    $signature = hash_hmac('sha256', $payload, $secretKeySavedBefore);
    
    if ($signature !== $receivedSignature) {
      exit('hash computed and sent in the request are not the same');
    }
    

    Every webhook sent to you is signed. With this signature you can be sure that nothing in the body has changed.

    To compute this signature on your own side, you have to save the secret key generated when a weebhook is created. This secret will be used to generate a hash.

    This keyed hash use the sha256 algorithm against the request payload.

    Create a webhook

    curl --include \
         --request POST \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"webhooks\",
            \"id\": \"338d5af0-cbbe-491f-913f-50fab162074d\",
            \"attributes\": {
                \"endpoint\": \"https://domain.tld/\",
                \"actions\": [
                    \"subscription.created\"
                ],
                \"label\": \"webhook optional label\",
                \"metadata\": {
                  \"custom_data\": \"value\"
                }
            }
        }
    }" \
    'https://api.pagaio.com/webhooks'
    

    The above command returns JSON structured like this:

    {
      "data": {
        "type": "webhooks",
        "id": "338d5af0-cbbe-491f-913f-50fab162074d",
        "links": {
          "self": "https://api.pagaio.com/webhooks/ab6ea76a-4ddf-4ea1-91d5-0b267d0c692d"
        },
        "attributes": {
          "endpoint": "https://domain.tld/",
          "actions": [
            "subscription.created"
          ],
          "secret": "a9210983ed58a1a3f2a80810d08f38f6dc8aa9c166341417f4",
          "created_at": "2017-06-19T12:36:22+00:00",
          "label": "webhook optional label",
          "metadata": {
            "custom_data": "value"
          }
        }
      }
    }
    

    This endpoint creates a new webhook.

    HTTP Request

    POST https://api.pagaio.com/webhooks

    Webhook attributes

    Name type mandatory Description
    endpoint string Yes endpoint fetched when a registered event occurs
    actions array Yes array containing all the actions used by this webhook
    label string No label allowing you to name your webhook
    metadata object No key-value data. You can specify up to 10 keys, with key names up to 40 characters long and values up to 500 characters long.

    List of actions :

    Update a webhook

    curl --include \
         --request PATCH \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"webhooks\",
            \"id\": \"338d5af0-cbbe-491f-913f-50fab162074d\",
            \"attributes\": {
                \"endpoint\": \"https://new-domain.tld/\",
                \"actions\": [
                    \"subscription.closed\"
                ],
                \"label\": \"updated label\",
                \"metadata\": {
                  \"custom_data\": \"value\"
                }
            }
        }
    }" \
    'https://api.pagaio.com/webhooks/338d5af0-cbbe-491f-913f-50fab162074d'
    

    This request will return

    {
      "data": {
        "type": "webhooks",
        "id": "338d5af0-cbbe-491f-913f-50fab162074d",
        "links": {
          "self": "https://api.pagaio.com/webhooks/ab6ea76a-4ddf-4ea1-91d5-0b267d0c692d"
        },
        "attributes": {
          "endpoint": "https://new-domain.tld/",
          "actions": [
            "subscription.closed"
          ],
          "secret": "a9210983ed58a1a3f2a80810d08f38f6dc8aa9c166341417f4",
          "created_at": "2017-06-19T12:36:22+00:00",
          "label": "updated label",
          "metadata": {
            "custom_data": "value"
          }
        }
      }
    }
    

    This endpoint update webhook's attributes. None are mandatory but at least one should be present. Missing attributes will not be replaced, the server will interpret the missing attributes as if they were included with their current values.

    HTTP Request

    PATCH https://api.pagaio.com/webhooks/{id}

    Webhook attributes

    Name type mandatory Description
    endpoint string No endpoint fetched when a registered event occurs
    actions array No array containing all the actions used by this webhook
    label string No label allowing you to name your webhook
    metadata object No key-value data. You can specify up to 10 keys, with key names up to 40 characters long and values up to 500 characters long.

    Retrieve a webhook

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/webhooks/338d5af0-cbbe-491f-913f-50fab162074d'
    

    This request will return

    {
      "data": {
        "type": "webhooks",
        "id": "338d5af0-cbbe-491f-913f-50fab162074d",
        "links": {
          "self": "https://api.pagaio.com/webhooks/ab6ea76a-4ddf-4ea1-91d5-0b267d0c692d"
        },
        "attributes": {
          "endpoint": "https://domain.tld/",
          "actions": [
            "subscription.created"
          ],
          "secret": "a9210983ed58a1a3f2a80810d08f38f6dc8aa9c166341417f4",
          "created_at": "2017-06-19T12:36:22+00:00"
        }
      }
    }
    

    HTTP Request

    GET https://api.pagaio.com/webhooks/{id}

    Url attributes

    Name type Description
    id UUID The unique webhook identifier

    Retrieve all webhooks

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/webhooks'
    

    This request will return

    {
      "data": [{
        "type": "webhooks",
        "id": "338d5af0-cbbe-491f-913f-50fab162074d",
        "links": {
          "self": "https://api.pagaio.com/webhooks/ab6ea76a-4ddf-4ea1-91d5-0b267d0c692d"
        },
        "attributes": {
          "endpoint": "https://domain.tld/",
          "actions": [
            "subscription.created"
          ],
          "secret": "a9210983ed58a1a3f2a80810d08f38f6dc8aa9c166341417f4",
          "created_at": "2017-06-19T12:36:22+00:00"
        }
      }]
    }
    

    This endpoint will return all configured webhooks in your account. data is a webhook array

    HTTP Request

    GET https://api.pagaio.com/webhooks

    Delete a webhook

    curl --include \
         --request DELETE \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
       'https://api.pagaio.com/webhooks/{id}'
    

    This request return an empty response (status code 204)

    Delete a webhook is a permanent action, it will not be possible to revert it after.

    HTTP Request

    DELETE https://api.pagaio.com/webhooks/{id}

    Url attributes

    Name type Description
    id UUID The unique webhook identifier

    Contracts

    Contract is the base entity to create describe the product to sell. A contract will hold many clauses to describe how this contract will work.

    Create a contract

    curl --include \
         --request POST \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"contracts\",
            \"id\": \"125b3b5e-622d-435e-94ea-7081767c9d84\",
            \"attributes\": {
                \"title\": \"my super contract\",
                \"description\": \"my contract description\",
                \"currency\": \"EUR\",
                \"success_url\": \"https://domain.tld/success\",
                \"cancel_url\": \"https://domain.tld/cancel\"
            }
        }
    }" \
    'https://api.pagaio.com/contracts'
    

    This request will return

    {
      "data": {
        "type": "contracts",
        "id": "125b3b5e-622d-435e-94ea-7081767c9d84",
        "links": {
          "self": "https://api.pagaio.com/contracts/125b3b5e-622d-435e-94ea-7081767c9d84"
        },
        "attributes": {
          "title": "my super contract",
          "description": "my contract description",
          "currency": "EUR",
          "created_at": "2017-03-03T10:49:27+00:00",
          "success_url": "https://domain.tld/success",
          "cancel_url": "https://domain.tld/cancel"
        }
      }
    }
    

    HTTP Request

    POST https://api.pagaio.com/contracts

    Contract attributes

    Name type mandatory Description
    title string Yes contract title
    description string No contract description
    currency string Yes ISO 4217 currency code
    success_url string No url where your customer will be redirected after they saved their payment method.
    cancel_url string No url where your customer will be redirected if they don't save their payment method.

    Retrieve a contract

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/contracts/{id}'
    

    This request will return

    {
      "data": {
        "type": "contracts",
        "id": "ebe77c8d-9c6f-4d20-88db-23487e22416a",
        "links": {
          "self": "https://api.pagaio.com/contracts/ebe77c8d-9c6f-4d20-88db-23487e22416a"
        },
        "attributes": {
          "title": "my super contract",
          "description": "my contract description",
          "currency": "EUR",
          "success_url": "https://domain.tld/success",
          "cancel_url": "https://domain.tld/cancel",
          "created_at": "2017-03-03T10:49:00+00:00"
        },
        "relationships": {
          "clauses": {
            "links": {
              "self": "https://api.pagaio.com/contracts/ebe77c8d-9c6f-4d20-88db-23487e22416a/relationships/clauses"
            },
            "data": [
              {
                "type": "clauses",
                "id": "1fa596ea-2e90-4f9b-a497-d1b382fb0d2a"
              }
            ]
          }
        }
      },
      "included": [
        {
          "type": "clauses",
          "id": "1fa596ea-2e90-4f9b-a497-d1b382fb0d2a",
          "links": {
            "self": "https://api.pagaio.com/clauses/1fa596ea-2e90-4f9b-a497-d1b382fb0d2a"
          },
          "attributes": {
            "type": "subscription",
            "attributes": {
              "price": 900,
              "recurrence_unit": 1,
              "recurrence_period": "month"
            }
          }
        }
      ]
    }
    

    HTTP Request

    GET https://api.pagaio.com/contracts/{id}

    Url attributes

    Name type Description
    id UUID The unique contract identifier

    relationships

    all the clauses defined in this contract will be included in the response

    Retrieve all contracts

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/contracts?page[number]=3'
    

    This request will return

    {
      "meta": {
        "page": {
          "first": 1,
          "last": 5,
          "current": 3
        }
      },
      "links": {
        "first": "http://api.pagaio.com/contracts?page%5Bnumber%5D=1",
        "last": "http://api.pagaio.com/contracts?page%5Bnumber%5D=5",
        "prev": "http://api.pagaio.com/contracts?page%5Bnumber%5D=2",
        "next": "http://api.pagaio.com/contracts?page%5Bnumber%5D=4",
        "self": "http://api.pagaio.com/contracts?page%5Bnumber%5D=3"
      },
      "data": [
        {
          "type": "contracts",
          "id": "7decf275-9511-46fa-ad0a-e1592e484304",
          "links": {
            "self": "https://api.pagaio.com/contracts/7decf275-9511-46fa-ad0a-e1592e484304"
          },
          "attributes": {
            "title": "my super contract",
            "description": "my contract description",
            "currency": "EUR",
            "success_url": "https://domain.tld/success",
            "cancel_url": "https://domain.tld/cancel",
            "created_at": "2017-06-16T13:33:41+00:00"
          }
        },
        {
          "type": "contracts",
          "id": "ebe77c8d-9c6f-4d20-88db-23487e22416a",
          "links": {
            "self": "https://api.pagaio.com/contracts/ebe77c8d-9c6f-4d20-88db-23487e22416a"
          },
          "attributes": {
            "title": "monthly contract",
            "description": "my contract description",
            "currency": "EUR",
            "created_at": "2017-06-16T13:33:41+00:00"
          }
        },
        {
          "type": "contracts",
          "id": "ce45492c-0d5f-43d2-b05b-c122bcc71f73",
          "links": {
            "self": "https://api.pagaio.com/contracts/ce45492c-0d5f-43d2-b05b-c122bcc71f73"
          },
          "attributes": {
            "title": "daily contract",
            "description": "my contract description",
            "currency": "EUR",
            "success_url": "https://domain.tld/success",
            "cancel_url": "https://domain.tld/cancel",
            "created_at": "2017-06-16T13:33:41+00:00"
          }
        },
        {
          "type": "contracts",
          "id": "f6977390-3595-403c-8550-f7a6ba668624",
          "links": {
            "self": "https://api.pagaio.com/contracts/f6977390-3595-403c-8550-f7a6ba668624"
          },
          "attributes": {
            "title": "contract product A",
            "description": "my contract description",
            "currency": "EUR",
            "success_url": "https://domain.tld/success",
            "cancel_url": "https://domain.tld/cancel",
            "created_at": "2017-06-16T13:33:41+00:00"
          }
        },
        {
          "type": "contracts",
          "id": "5cfdeda5-0199-4d9a-bb59-7deacf875f5f",
          "links": {
            "self": "https://api.pagaio.com/contracts/5cfdeda5-0199-4d9a-bb59-7deacf875f5f"
          },
          "attributes": {
            "title": "contract product B",
            "description": "my contract description",
            "currency": "EUR",
            "success_url": "https://domain.tld/success",
            "cancel_url": "https://domain.tld/cancel",
            "created_at": "2017-06-16T13:33:41+00:00"
          }
        },
        {
          "type": "contracts",
          "id": "125b3b5e-622d-435e-94ea-7081767c9d84",
          "links": {
            "self": "https://api.pagaio.com/contracts/125b3b5e-622d-435e-94ea-7081767c9d84"
          },
          "attributes": {
            "title": "my super contract",
            "description": "my contract description",
            "currency": "EUR",
            "success_url": "https://domain.tld/success",
            "cancel_url": "https://domain.tld/cancel",
            "created_at": "2017-06-16T13:36:26+00:00"
          }
        }
      ]
    }
    

    This endpoint will return a collection of contracts defined for the account linked to the api key used fir this request.

    HTTP Request

    GET https://api.pagaio.com/contracts?page[number]={number}

    pagination

    this endpoint is paginated and return 20 items per page. For now it is not possible to change the size. In the query string you can change the page number using the page[number] parameter. In the response you will have several about the pagination. In the meta section you have information about the page number and in the links section you can retrieve several links to navigate between the available pages.

    Update a contract

    curl --include \
         --request PATCH \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"contracts\",
            \"id\": \"125b3b5e-622d-435e-94ea-7081767c9d84\",
            \"attributes\": {
                \"title\": \"updated title\",
                \"description\": \"updated description\",
                \"currency\": \"EUR\",
                \"success_url\": \"https://domain.tld/success-new\",
                \"cancel_url\": \"https://domain.tld/cancel-new\"
            }
        }
    }" \
    'https://api.pagaio.com/contracts/125b3b5e-622d-435e-94ea-7081767c9d84'
    

    This request will return

    {
      "data": {
        "type": "contracts",
        "id": "125b3b5e-622d-435e-94ea-7081767c9d84",
        "links": {
          "self": "https://api.pagaio.com/contracts/125b3b5e-622d-435e-94ea-7081767c9d84"
        },
        "attributes": {
          "title": "updated title",
          "description": "updated description",
          "currency": "EUR",
          "created_at": "2017-03-03T10:49:27+00:00",
          "success_url": "https://domain.tld/success-new",
          "cancel_url": "https://domain.tld/cancel-new"
        }
      }
    }
    

    This endpoint update a contract. The currency attributes will never be updated. Missing attributes will not be replaced, the server will interpret the missing attributes as if they were included with their current values.

    HTTP Request

    PATCH https://api.pagaio.com/contracts/{id}

    Contract attributes

    Name type mandatory Description
    title string No contract title. Can't be blank.
    description string No contract description.
    success_url string No url where your customer will be redirected after they saved their payment method.
    cancel_url string No url where your customer will be redirected if they don't save their payment method.

    Retry payment

    When a payment fails, you can manage how it can be retry. You can create how many retry you want for a contract. A contract without retry rule will close the subscription after the first payment failure.

    Create a retry rule

    curl --include \
         --request POST \
         --header "Accept: application/vnd.api+json" \
         --header "Content-Type: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"retries\",
            \"id\": \"a19c0462-2c5e-4caf-8759-09c15d7a1cbc\",
            \"attributes\": {
                \"day\": 1
            },
            \"relationships\": {
                \"contracts\": {
                    \"data\": {
                        \"type\": \"contracts\",
                        \"id\": \"8aaaee6a-2556-4c7c-9087-6bc61c0af710\"
                    }
                }
            }
        }
    }" \
    'https://api.pagaio.com/retries'
    

    This request will return

    {
        "data": {
            "type": "retries",
            "id": "a19c0462-2c5e-4caf-8759-09c15d7a1cbc",
            "attributes": {
                "day": 1
            },
            "relationships": {
                "contracts": {
                    "data": {
                        "type": "contracts",
                        "id": "8aaaee6a-2556-4c7c-9087-6bc61c0af710"
                    }
                }
            }
        },
        "included": [{
            "type": "contracts",
            "id": "8aaaee6a-2556-4c7c-9087-6bc61c0af710",
            "links": {
                "self": "https://api.pagaio.com/contracts/8aaaee6a-2556-4c7c-9087-6bc61c0af710"
            },
            "attributes": {
                "title": "contract to add retries rules",
                "description": "contract to add retries rules",
                "currency": "EUR",
                "successful_url": "",
                "cancel_url": "",
                "created_at": "2017-12-18T09:53:08+00:00",
                "status": "pending"
            }
        }]
    }
    

    HTTP request

    POST https://api.pagaio.com/retries

    Retry attributes

    Name type mandatory Description
    day integer yes Number of day before retrying a failed payment. eg : 1, will reschedule the payment 1 day after the payment failure date.

    Update a retry

    curl --include \
         --request PATCH \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"retries\",
            \"id\": \"86b55094-a4fa-4300-8611-8a85d0898196\",
            \"attributes\": {
                \"day\": 2
            }
        }
    }" \
    'https://api.pagaio.com/retries/86b55094-a4fa-4300-8611-8a85d0898196'
    

    This request will return

    {
        "data": {
            "type": "retries",
            "id": "86b55094-a4fa-4300-8611-8a85d0898196",
            "attributes": {
                "day": 2
            },
            "relationships": {
                "contracts": {
                    "data": {
                        "type": "contracts",
                        "id": "c6733a53-8fc9-47c5-bac4-cf294c4eb95b"
                    }
                }
            }
        },
        "included": [{
            "type": "contracts",
            "id": "c6733a53-8fc9-47c5-bac4-cf294c4eb95b",
            "links": {
                "self": "https://api.pagaio.com/contracts/c6733a53-8fc9-47c5-bac4-cf294c4eb95b"
            },
            "attributes": {
                "title": "contract with retry rule to update",
                "description": "contract with retry rule to update",
                "currency": "EUR",
                "successful_url": "",
                "cancel_url": "",
                "created_at": "2017-12-18T10:01:44+00:00",
                "status": "pending"
            }
        }]
    }
    

    HTTP Request

    PATCH https://api.pagaio.com/retries/{id}

    Retry attributes

    Name type mandatory Description
    day integer yes Number of day before retrying a failed payment. eg : 1, will reschedule the payment 1 day after the payment failure date.

    Retrieve a retry

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/retries/7f023397-4665-4836-808c-588fa8e4d2d8'
    

    This request will return

    {
        "data": {
            "type": "retries",
            "id": "7f023397-4665-4836-808c-588fa8e4d2d8",
            "attributes": {
                "day": 4
            },
            "relationships": {
                "contracts": {
                    "data": {
                        "type": "contracts",
                        "id": "8aaaee6a-2556-4c7c-9087-6bc61c0af710"
                    }
                }
            }
        },
        "included": [{
            "type": "contracts",
            "id": "8aaaee6a-2556-4c7c-9087-6bc61c0af710",
            "links": {
                "self": "https://api.pagaio.com/contracts/8aaaee6a-2556-4c7c-9087-6bc61c0af710"
            },
            "attributes": {
                "title": "contract to add retries rules",
                "description": "contract to add retries rules",
                "currency": "EUR",
                "successful_url": "",
                "cancel_url": "",
                "created_at": "2017-12-18T10:01:44+00:00",
                "status": "pending"
            }
        }]
    }
    

    HTTP Request

    GET https://api.pagaio.com/retries/{id}

    Url attributes

    Name type Description
    id UUID The unique retry identifier

    Retrieve all retries rules

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/contracts/9dbc8f82-d972-4840-b442-5702cb06f043/relationships/retries'
    

    This request will return

    {
        "data": [{
            "type": "retries",
            "id": "9a61fadf-457f-468f-a461-4c855c91aa60",
            "attributes": {
                "day": 4
            },
            "relationships": {
                "contracts": {
                    "data": {
                        "type": "contracts",
                        "id": "9dbc8f82-d972-4840-b442-5702cb06f043"
                    }
                }
            }
        }, {
            "type": "retries",
            "id": "0f6e5f39-da33-482b-8bd6-bf6233bf1e16",
            "attributes": {
                "day": 5
            },
            "relationships": {
                "contracts": {
                    "data": {
                        "type": "contracts",
                        "id": "9dbc8f82-d972-4840-b442-5702cb06f043"
                    }
                }
            }
        }],
        "included": [{
            "type": "contracts",
            "id": "9dbc8f82-d972-4840-b442-5702cb06f043",
            "links": {
                "self": "https://api.pagaio.com/contracts/9dbc8f82-d972-4840-b442-5702cb06f043"
            },
            "attributes": {
                "title": "contract to add retries rules",
                "description": "contract to add retries rules",
                "currency": "EUR",
                "successful_url": "",
                "cancel_url": "",
                "created_at": "2017-12-18T10:01:44+00:00",
                "status": "pending"
            }
        }]
    }
    

    data property contains a retries collection.

    HTTP Request

    GET https://api.pagaio.com/contracts/{contractId}/relationships/retries

    Url attributes

    Name type Description
    contractId UUID The unique contract identifier containing the retries rules

    Clauses

    A clause is a condition added in a contract. There are several type of Clauses and each clause has its own attributes.

    Create a clause

    example for a subscription type clause

    curl --include \
         --request POST \
         --header "Accept: application/vnd.api+json" \
         --header "Content-Type: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"clauses\",
            \"id\": \"030800d8-9ae3-4bbe-87f2-cbb37eb0fe70\",
            \"attributes\": {
                \"type\": \"subscription\",
                \"attributes\": {
                    \"price\": \"9.50\",
                    \"recurrence_unit\": 1,
                    \"recurrence_period\": \"month\"
                },
                \"name\": \"clause name\",
                \"description\": \"clause description explaining the purpose of this one.\",
                \"enabled\": true
            },
            \"relationships\": {
                \"contracts\": {
                    \"data\": {
                        \"type\": \"contracts\",
                        \"id\": \"ce45492c-0d5f-43d2-b05b-c122bcc71f73\"
                    }
                }
            }
        }
    }" \
    'https://api.pagaio.com/clauses'
    

    This request will return

    {
      "data": {
        "type": "clauses",
        "id": "030800d8-9ae3-4bbe-87f2-cbb37eb0fe70",
        "links": {
          "self": "https://api.pagaio.com/clauses/030800d8-9ae3-4bbe-87f2-cbb37eb0fe70"
        },
        "attributes": {
          "type": "subscription",
          "attributes": {
            "price": "9.50",
            "recurrence_unit": 1,
            "recurrence_period": "month"
          },
          "name": "clause name",
          "description": "clause description explaining the purpose of this one.",
          "enabled": true
        }
      }
    }
    

    HTTP request

    POST https://api.pagaio.com/clauses

    Clause attributes

    Name type mandatory Description
    type string Yes clause type. Each type available are listed below.
    attributes array Yes Clause attributes. Every clauses have different attributes. They are described below.
    name string No Clause name to identify it easily. For some clauses. like subscription or trial this is useless. For an optional clause it is better to use it.
    description string No Clause description to detail what is the purpose of this clause.
    enabled boolean No determine if the clause will be enabled by default when a new subscription will be created. If not used, the default clause behavior will be applied. See amendment to know hot to change its value only on a subscription.

    relationships

    A clause always belong to a contract so you must put the contract to use in the relationships. In the relationships property, a contracts property must be declared containing the following data :

    Name type mandatory Description
    id UUID Yes the contract identifier to use
    type string Yes must be contracts

    Clause type

    Price clause

    This clause type is price. It set a price to a subscription

    enabled by default

    Name type Description
    price numeric recurrence price

    Schedule clause

    This clause type id schedule. It defines the recurrence of your contract.

    enabled by default.

    Name type Description
    recurrence_unit integer recurrence interval between two payments. Example : 20
    recurrence_period string can be day or month

    Schedule clause at constant date

    This clause type is schedule_fix and it defines the recurrence of your contract every same day in the month (eg: every 1st day)

    enabled by default

    Name type Description
    day integer day of the month chosen. Value can be between 1 and 28 included. Example : 20.
    proration boolean pay proportionally the first month. If the first subscription month contains only 3 days, pay 3 days. Default false

    Schedule clause every month's last day

    This clause type is schedule_last_day and it defines the recurrence of your contract every month's last day

    enabled by default.

    Name type Description
    proration boolean pay proportionally the first month. If the first subscription month contains only 3 days, pay 3 days. Default false

    Subscription clause

    This clause type is subscription and is the main clause to use to create a recurrent payment. It is the combination of price and schedule clauses. The given price will be applied every recurrence time defined in the attributes :

    enabled by default.

    Name type Description
    price numeric recurrence price
    recurrence_unit integer recurrence interval between two payments. Example : 20
    recurrence_period string can be day or month

    Minimum price clause

    This clause is type minimum_price. You define a price and this price will be used only if at the end of the period the amount is smaller than the defined price.

    enabled by default

    Name type Description
    price numeric minimum price

    Trial clause

    This clause type is trial. Its purpose is to delay the first payment for a trial period. During this period no payment will be done. The first payment will be done once the period indicated ended. The price of this first payment can be changed to give a discount to you customer

    enabled by default.

    Name type Description
    price numeric trial clause price
    unit integer interval with next payment
    period string can be day or month

    First payment clause

    This clause type is first_payment. Its purpose is to force the first payment when the customer enter its payment information. For all the other clauses (subscription, trial, etc) the first payment will be done at the end of the first period. If you want to force it at the beginning of the first period you should use this clause.

    This clause has no attributes, use an empty object ({}) in your request payload at path data.attributes.attributes.

    enabled by default.

    Optional clause

    This clause is type optional. Its purpose is to add an option to your contract. This option will be disabled by default and can be enabled via an amendment. See amendment chapter. The option will be applied for every recurrent payment. A quantity can be set if you want to apply more than once this option. By default the quantity is set to 1 and must but greater than 0. No period can be defined.

    Disabled by default.

    Name type Description
    price numeric option price
    quantity integer quantity applied to this option. Default is 1, if you set it to 2 the price will be multiply by 2. This property is not mandatory, if you don't set it, 1 will be applied

    Metered clauses

    curl --include \
         --request PATCH \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"subscription_history_extradatas\",
            \"id\": \"a5d91259-d8a1-47df-9d0c-342d47bbc28c\",
            \"attributes\": {
                \"attributes\": {
                    \"volume\": 42
                }
            }
        }
    }" \
    'https://api.pagaio.com/subscription_history_extradatas/a5d91259-d8a1-47df-9d0c-342d47bbc28c'
    

    This request will return

    {
        "data": {
            "type": "subscription_history_extradatas",
            "id": "a5d91259-d8a1-47df-9d0c-342d47bbc28c",
            "attributes": {
                "attributes": {
                    "volume": 100
                }
            },
            "relationships": {
                "subscription_clauses": {
                    "data": {
                        "type": "subscription_clauses",
                        "id": "a0b76741-a91a-4744-a951-cd7c2778705b"
                    }
                },
                "subscription_history": {
                    "data": {
                        "type": "subscription_history",
                        "id": "81cf1130-d4b0-4e2a-bb44-be3d3be52568"
                    }
                }
            }
        },
        "included": [{
            "type": "subscription_clauses",
            "id": "a0b76741-a91a-4744-a951-cd7c2778705b",
            "attributes": {
                "type": "metered",
                "attributes": {
                    "unit_price": "0.015",
                    "initial_volume": 0
                },
                "enabled": true,
                "name": "",
                "description": ""
            }
        }, {
            "type": "subscription_history",
            "id": "81cf1130-d4b0-4e2a-bb44-be3d3be52568",
            "links": {
                "self": "http://api.pagaio.com/subscriptions/75d8b92f-7f0e-4bcb-b866-e2e8b789d5a6/histories/81cf1130-d4b0-4e2a-bb44-be3d3be52568"
            },
            "attributes": {
                "scheduled_at": "2017-12-03T08:13:11+00:00",
                "status": "scheduled",
                "amount": {},
                "info": [],
                "process_at": null,
                "executed_at": null,
                "retry": true,
                "subscription_id": "75d8b92f-7f0e-4bcb-b866-e2e8b789d5a6"
            }
        }]
    }
    

    Some clauses have a special behaviour. They don't have a constant price and the price can be compute following different rules. Before each payment, the price will be computed by applying the rules defined and after the payment the clause will be reset.

    Resetable clauses can compute a price by applying a unit price to a volume (0.05€/sms) or a percent of this volume (0.40% of a global amount). The volume must be defined by yourself before a subscription is in processing status. Each time you update the volume, the new price will be computed.

    Update the volume

    To update the volume you will have to patch a subscription_history_extradata resources. When a subscription_history is created, those resources are side-loaded in the payload. So you must have a webhook listening the payment.scheduled event to keep the id of each resources you would like to update.

    HTTP Request

    GET https://api.pagaio.com/subscription_history_extradatas/{id}

    Url attributes

    Name type Description
    id UUID The unique contract identifier containing the clauses

    Metered clauses type

    Metered clause

    This clause is type metered and will be reset after each payment. You define a unit_price and at the end of the period, this unit_price will be multiply by a volume defined by yourself. An initial_volume can be set, it will initialize the volume at the beginning of each period.

    enabled by default

    Name type Description
    unit_price numeric recurrence unit price
    initial_volume numeric set the volume for each beginning period

    Percent clause

    This clause is type percent_volume and will be reset after each payment. You define a percent and at the end of the period, this percent will be used on a volume defined by yourself. An initial_volume can be set, it will initialize the volume at the beginning of each period.

    enabled by default

    Name type Description
    percent numeric percent between 0 and 100 (0 and 100 excluded)
    initial_volume numeric set the volume for each beginning period

    Retrieve a clause

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/clauses/{id}'
    

    This request will return

    {
      "data": {
        "type": "clauses",
        "id": "030800d8-9ae3-4bbe-87f2-cbb37eb0fe70",
        "links": {
          "self": "https://api.pagaio.com/clauses/030800d8-9ae3-4bbe-87f2-cbb37eb0fe70"
        },
        "attributes": {
          "type": "subscription",
          "attributes": {
            "price": "9.50",
            "recurrence_unit": 1,
            "recurrence_period": "month"
          },
          "name": "clause name",
          "description": "clause description explaining the purpose of this one.",
          "enabled": true
        }
      }
    }
    

    HTTP Request

    GET https://api.pagaio.com/clauses/{id}

    Url attributes

    Name type Description
    id UUID The unique clause identifier

    Retrieve all clauses

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/contracts/{contractId}/relationships/clauses'
    

    This request will return

    {
        "data": [{
            "type": "clauses",
            "id": "1fa596ea-2e90-4f9b-a497-d1b382fb0d2a",
            "links": {
                "self": "https://api.pagaio.com/clauses/1fa596ea-2e90-4f9b-a497-d1b382fb0d2a"
            },
            "attributes": {
                "type": "subscription",
                "attributes": {
                    "price": "9.50",
                    "recurrence_unit": 1,
                    "recurrence_period": "month"
                },
          "name": "clause name",
          "description": "clause description explaining the purpose of this one.",
          "enabled": true
            }
        }]
    }
    

    data property contains a clauses collection,

    HTTP Request

    GET https://api.pagaio.com/contracts/{contractId}/relationships/clauses

    Url attributes

    Name type Description
    contractId UUID The unique contract identifier containing the clauses

    Update a clause

    curl --include \
         --request PATCH \
         --header "Accept: application/vnd.api+json" \
         --header "Content-Type: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"clauses\",
            \"id\": \"030800d8-9ae3-4bbe-87f2-cbb37eb0fe70\",
            \"attributes\": {
                \"type\": \"subscription\",
                \"attributes\": {
                    \"price\": \"8\",
                    \"recurrence_unit\": 10,
                    \"recurrence_period\": \"day\"
                },
                \"name\": \"clause name\",
                \"description\": \"clause description explaining the purpose of this one.\",
                \"enabled\": false
            }
        }
    }" \
    'https://api.pagaio.com/clauses/030800d8-9ae3-4bbe-87f2-cbb37eb0fe70'
    

    This request will return

    {
      "data": {
        "type": "clauses",
        "id": "030800d8-9ae3-4bbe-87f2-cbb37eb0fe70",
        "links": {
          "self": "https://api.pagaio.com/clauses/030800d8-9ae3-4bbe-87f2-cbb37eb0fe70"
        },
        "attributes": {
          "type": "subscription",
          "attributes": {
            "price": "8",
            "recurrence_unit": 10,
            "recurrence_period": "day"
          },
          "name": "clause name",
          "description": "clause description explaining the purpose of this one.",
          "enabled": false
        }
      }
    }
    

    This endpoint update a clause. Only type attribute is mandatory. Missing attributes will not be replaced, the server will interpret the missing attributes as if they were included with their current values. When you update a clause, the existing subscription linked to the contract will not be updated. If you want to update them you have to create an amendment

    HTTP Request

    PATCH https://api.pagaio.com/clauses/{id}

    Clause attributes

    Name Type Mandatory Description
    type string yes clause type. This type must be the exact same as the updated clause
    attributes array No Clause attributes. Every clauses have different attributes. You can change their values here
    name string No Clause name to identify it easily.
    description string No Clause description to detail what is the purpose of this clause.
    enabled boolean No determine if the clause will be enabled by default when a new subscription will be created. If not used, the default clause behavior will be applied. See amendment to know hot to change its value only on a subscription.

    Delete a clause

    curl --include \
         --request DELETE \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
       'https://api.pagaio.com/clauses/{id}'
    

    This request return an empty response (status code 204)

    Delete a clause is a permanent action, it will not be possible to revert it after.

    HTTP Request

    DELETE https://api.pagaio.com/clauses/{id}

    Url attributes

    Name type Description
    id UUID The unique clause identifier

    Payments

    Configure a stripe payment

    curl --include \
         --request POST \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"payments\",
            \"id\": \"87b25264-5bbe-4aa6-a877-7e265d1b0e60\",
            \"attributes\": {
                \"type\": \"stripe\",
                \"attributes\": {
                    \"secret_test_key\": \"your stripe test api key\",
                    \"secret_live_key\": \"your stripe live api key\",
                    \"publishable_test_key\": \"your publishable test api key\",
                    \"publishable_live_key\": \"your publishable live api key\"
                }
            }
        }
    }" \
    'https://api.pagaio.com/payments'
    

    This request will return

    {
        "data": {
            "type": "payments",
            "id": "87b25264-5bbe-4aa6-a877-7e265d1b0e60",
            "links": {
                "self": "https://api.pagaio.com//payments/87b25264-5bbe-4aa6-a877-7e265d1b0e60"
            },
            "attributes": {
                "type": "stripe",
                "attributes": {
                    "secret_test_key": "your stripe test api key",
                    "secret_live_key": "your stripe live api key",
                    "publishable_test_key": "your publishable test api key",
                    "publishable_live_key": "your publishable live api key"
                }
            }
        }
    }
    

    To use stripe with pagaio, you need to retrieve your stripe api keys. These keys are available in your stripe dashboard : https://dashboard.stripe.com/account/apikeys

    HTTP Request

    GET https://api.pagaio.com/contracts/payments

    payments attributes

    Name type Description
    type string must be stripe
    attributes array must contains the secret_test_key, secret_live_key, publishable_test_key and publishable_live_key. All this information are available in your stripe dashboard.

    Configure a payzen payment

    curl --include \
         --request POST \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
          \"type\": \"payments\",
          \"id\": \"dc0c9805-1e1f-4b83-99c5-8c7e31a9c2b8\",
          \"attributes\": {
            \"type\": \"payzen\",
            \"attributes\": {
              \"username\": \"69876357\",
              \"private_test_key\": \"testprivatekey_DEMOPRIVATEKEY23G4475zXZQ2UA5x7M\",
              \"public_test_key\": \"69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5\",
              \"private_production_key\": \"your private production key\",
              \"public_production_key\": \"your public production key\"
            }
          }
        }
      }" \
    'https://api.pagaio.com/payments'
    

    This request will return

    {
        "data": {
            "type": "payments",
            "id": "dc0c9805-1e1f-4b83-99c5-8c7e31a9c2b8",
            "links": {
                "self": "https://api.pagaio.com/payments/dc0c9805-1e1f-4b83-99c5-8c7e31a9c2b8"
            },
            "attributes": {
                "type": "payzen",
                "attributes": {
                    "username": "69876357",
                    "private_test_key": "testprivatekey_DEMOPRIVATEKEY23G4475zXZQ2UA5x7M",
                    "public_test_key": "69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5",
                    "private_production_key": "your private production key",
                    "public_production_key": "your public production key"
                }
            }
        }
    }
    

    To use Payzen with pagaio, you need to retrieve your payzen credentials. These credentials are available in your payzen dashboard. You can have more information here : https://payzen.io/en-EN/rest-api/card/integration/get-my-keys.html#getting-your-authentication-information

    HTTP Request

    GET https://api.pagaio.com/contracts/payments

    payments attributes

    Name type Description
    type string must be payzen
    attributes array must contains the username, private_test_key, public_test_key, private_production_key and public_production_key. All this information are available in your payzen dashboard.

    Configure a GoCardLess payment

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/payments/gocardless'
    

    This request will return

    {
      "url": "redirect your user to this url"
    }
    

    To use GoCardLess you have first to create both a test ans production account. If you don't have one, the redirection link allow you to create one.

    For this payment method, you will have to do this operation twice, to link your pagaio test account with your gocardless test account and to link your pagaio production account with your gocardless production account. The link generated with this endpoint depends on the api key you use. With a test api key, you will have a link to the gocardless test platform and with a live api key you will have a link to the gocardless production platform.

    GoCardless uses a redirection flow to link your GoCardless account to your Pagaio account. Pagaio will first generate a dynamic link and your client will redirect to this link and then follow the gocardless instructions.

    Retrieve payment info

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/payments/{id}'
    

    This request will return

    {
      "data": {
        "type": "payments",
        "id": "cb269e9c-a2b1-49fe-9031-2b257528db32",
        "links": {
          "self": "https://api.pagaio.com/payments/cb269e9c-a2b1-49fe-9031-2b257528db32"
        },
        "attributes": {
          "type": "stripe",
          "attributes": {
            "secret_test_key": "your stripe test api key",
            "secret_live_key": "your stripe live api key",
            "publishable_test_key": "your publishable test api key",
            "publishable_live_key": "your publishable live api key"
          }
        }
      }
    }
    

    Depending the payment type you retrieve, the info in the response will change according to the payment attributes.

    HTTP Request

    GET https://api.pagaio.com/payments/{id}

    Url attributes

    Name type Description
    id UUID The unique payment identifier

    Retrieve all payments configured

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/payments'
    

    This request will return

    {
      "data": [
        {
          "type": "payments",
          "id": "e1cf527a-6a1e-4582-bf1f-a73712b9e1ec",
          "links": {
            "self": "https://api.pagaio.com/payments/e1cf527a-6a1e-4582-bf1f-a73712b9e1ec"
          },
          "attributes": {
            "type": "GoCardLess",
            "attributes": {
              "test": {
                "token": "your GoCardLess app token",
                "organisation": "your GoCardless organisation id"
              }
            }
          }
        },
        {
          "type": "payments",
          "id": "cb269e9c-a2b1-49fe-9031-2b257528db32",
          "links": {
            "self": "https://api.pagaio.com/payments/cb269e9c-a2b1-49fe-9031-2b257528db32"
          },
          "attributes": {
            "type": "stripe",
            "attributes": {
              "secret_test_key": "your stripe test api key",
              "secret_live_key": "your stripe live api key",
              "publishable_test_key": "your publishable test api key",
              "publishable_live_key": "your publishable live api key"
            }
          }
        }
      ]
    }
    

    Customers

    Create a customer

    curl --include \
         --request POST \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "  {
        \"data\": {
          \"type\": \"customers\",
          \"id\": \"931a3795-8722-48b9-b2d3-521e3435adb3\",
          \"attributes\": {
            \"fullname\": \"John Doe\",
            \"email\": \"john.doe@paga.io\",
            \"metadata\": {
              \"data\": \"value\"
            }
          }
        }
      }" \
    'https://api.pagaio.com/customers'
    

    This request will return

    
    {
      "data": {
        "type": "customers",
        "id": "931a3795-8722-48b9-b2d3-521e3435adb3",
        "links": {
          "self": "https://api.pagaio.com/customers/931a3795-8722-48b9-b2d3-521e3435adb3"
        },
        "attributes": {
          "fullname": "John Doe",
          "email": "john.doe@paga.io",
          "created_at": "2017-06-16T08:21:30+00:00",
          "metadata": {
            "data": "value"
          }
        }
      }
    }
    

    HTTP Request

    POST https://api.pagaio.com/customers

    Contract attributes

    Name type mandatory Description
    fullname string Yes customer first name
    email string Yes customer email. This email is not unique in your application so you can have multiple customer with the same email.
    metadata object No key-value data. You can specify up to 10 keys, with key names up to 40 characters long and values up to 500 characters long.

    Retrieve a customer

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/customers/{id}'
    

    This request will return

    {
        "data": {
            "type": "customers",
            "id": "fbc22370-2fe1-448c-bdd0-aae228b571d6",
            "links": {
                "self": "https://api.pagaio.com/customers/fbc22370-2fe1-448c-bdd0-aae228b571d6"
            },
            "attributes": {
                "fullname": "John Doe",
                "email": "john.doe@pagaio.com",
                "created_at": "2017-11-22T10:50:32+00:00",
                "metadata": []
            }
        }
    }
    

    HTTP Request

    POST https://api.pagaio.com/customers/{id}

    Url attributes

    Name mandatory Description
    id UUID customer identifier

    Subscriptions

    Create a subscription

    in this request the customer will be created with the subscription

    curl --include \
         --request POST \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"subscriptions\",
            \"id\": \"9f3794a2-f9d2-4482-99f6-e88b624b7be7\",
            \"attributes\":{
                \"customer\": {
                    \"fullname\": \"john doe\",
                    \"email\": \"customer@periodable.com\"
                },
                \"metadata\": {
                  \"custom_data\": \"value\"
                }
            },
            \"relationships\": {
                \"contracts\": {
                    \"data\": {
                        \"type\": \"contracts\",
                        \"id\": \"ce45492c-0d5f-43d2-b05b-c122bcc71f73\"
                    }
                },
                \"payments\": {
                    \"data\": {
                        \"type\": \"payments\",
                        \"id\": \"cb269e9c-a2b1-49fe-9031-2b257528db32\"
                    }
                }
            }
        }
    }" \
    'https://api,paga.io/subscriptions'
    

    in this request the customer already exists and is put in the relationships

    curl --include \
         --request POST \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
            \"type\": \"subscriptions\",
            \"id\": \"9f3794a2-f9d2-4482-99f6-e88b624b7be7\",
            \"attributes\":{},
            \"relationships\": {
                \"contracts\": {
                    \"data\": {
                        \"type\": \"contracts\",
                        \"id\": \"ce45492c-0d5f-43d2-b05b-c122bcc71f73\"
                    }
                },
                \"payments\": {
                    \"data\": {
                        \"type\": \"payments\",
                        \"id\": \"cb269e9c-a2b1-49fe-9031-2b257528db32\"
                    }
                },
                \"customers\": {
                    \"data\": {
                        \"type\": \"customers\",
                        \"id\": \"e9051869-817f-410f-9c33-382b2df1abde\"
                    }
                }
            }
        }
    }" \
    'https://api.pagaio.com/subscriptions'
    

    This request will return

    {
      "data": {
        "type": "subscriptions",
        "id": "9f3794a2-f9d2-4482-99f6-e88b624b7be7",
        "links": {
          "self": "https://api.pagaio.com/subscriptions/9f3794a2-f9d2-4482-99f6-e88b624b7be7"
        },
        "attributes": {
          "status": "pending",
          "created_at": "2017-06-15T08:39:09+00:00",
          "payment_url": "https://test_1.paga.io/subscriptions/payments/9f3794a2-f9d2-4482-99f6-e88b624b7be7",
          "metadata": {
            "customer_data": "value"
          }
        },
        "relationships": {
          "contracts": {
            "links": {
              "self": "https://api.pagaio.com/app_dev.php/contracts/ce45492c-0d5f-43d2-b05b-c122bcc71f73"
            },
            "data": {
              "type": "contracts",
              "id": "ce45492c-0d5f-43d2-b05b-c122bcc71f73"
            }
          },
          "payments": {
            "links": {
              "self": "https://api.pagaio.com/payments/cb269e9c-a2b1-49fe-9031-2b257528db32"
            },
            "data": {
              "type": "payments",
              "id": "cb269e9c-a2b1-49fe-9031-2b257528db32"
            }
          },
          "customers": {
            "links": {
              "self": "https://api.apga.io/customers/c3ee1056-b650-4403-83ea-580d610cd086"
            },
            "data": {
              "type": "customers",
              "id": "c3ee1056-b650-4403-83ea-580d610cd086"
            }
          }
        }
      },
      "included": [
        {
          "type": "contracts",
          "id": "ce45492c-0d5f-43d2-b05b-c122bcc71f73",
          "links": {
            "self": "https://api.pagaio.com/contracts/ce45492c-0d5f-43d2-b05b-c122bcc71f73"
          },
          "attributes": {
            "title": "contract product A",
            "description": "my contract description",
            "currency": "EUR",
            "created_at": "2017-06-14T14:12:42+00:00"
          }
        },
        {
          "type": "customers",
          "id": "c3ee1056-b650-4403-83ea-580d610cd086",
          "links": {
            "self": "https://api.pagaio.com/customers/c3ee1056-b650-4403-83ea-580d610cd086"
          },
          "attributes": {
            "fullname": "john doe",
            "email": "customer@periodable.com",
            "created_at": "2017-06-15T08:39:09+00:00"
          }
        }
      ]
    }
    

    HTTP Request

    POST https://api.pagaio.com/subscriptions

    Subscription response

    the response provide the url where your customer must be redirected to enter their payment information This url is at the path data.attributes.payment_url.

    Subscription attributes

    A subscription will have attributes only if you want to create the customer (the subscriber) in the same time you create the subscription. In this case you have to put a customer object in path data.attributes. This customer object has the attributes below :

    Name type mandatory Description
    fullname string Yes customer fullname
    email string Yes customer email. This email is not unique in your application so you can have multiple customer with the same email.

    other attributes outside customer object :

    Name type mandatory Description
    metadata object No key-value data. You can specify up to 10 keys, with key names up to 40 characters long and values up to 500 characters long.

    Subscription relationships

    a subscription need relationships to be created. payments and contracts relationships are mandatory. customers relations should be used only of the customer already exists, if you provide both customers relationships and attributes an error will occurs.

    contracts relationships attributes :

    this attributes must be in a contracts object like the example above.

    Name type mandatory Description
    type string Yes must be contracts
    id UUID Yes contract unique identifier

    payments relationships attributes:

    this attributes must be in a payments object like the example above.

    Name type mandatory Description
    type string Yes must be payments
    id UUID Yes payment unique identifier

    customer relationships attributes:

    this attributes must be in a customers object like the example above.

    Name type mandatory Description
    type string Yes must be customers
    id UUID Yes customer unique identifier

    Retrieve a subscription

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/subscriptions/{id}'
    

    this request will return

    {
      "data": {
        "type": "subscriptions",
        "id": "9f3794a2-f9d2-4482-99f6-e88b624b7be7",
        "links": {
          "self": "https://api.pagaio.com/subscriptions/9f3794a2-f9d2-4482-99f6-e88b624b7be7"
        },
        "attributes": {
          "status": "pending",
          "created_at": "2017-06-15T08:39:09+00:00",
          "payment_url": "https://test_1.paga.io/subscriptions/payments/9f3794a2-f9d2-4482-99f6-e88b624b7be7"
        },
        "relationships": {
          "contracts": {
            "links": {
              "self": "https://api.pagaio.com/app_dev.php/contracts/ce45492c-0d5f-43d2-b05b-c122bcc71f73"
            },
            "data": {
              "type": "contracts",
              "id": "ce45492c-0d5f-43d2-b05b-c122bcc71f73"
            }
          },
          "payments": {
            "links": {
              "self": "https://api.pagaio.com/payments/cb269e9c-a2b1-49fe-9031-2b257528db32"
            },
            "data": {
              "type": "payments",
              "id": "cb269e9c-a2b1-49fe-9031-2b257528db32"
            }
          },
          "customers": {
            "links": {
              "self": "https://api.apga.io/customers/c3ee1056-b650-4403-83ea-580d610cd086"
            },
            "data": {
              "type": "customers",
              "id": "c3ee1056-b650-4403-83ea-580d610cd086"
            }
          }
        }
      },
      "included": [
        {
          "type": "contracts",
          "id": "ce45492c-0d5f-43d2-b05b-c122bcc71f73",
          "links": {
            "self": "https://api.pagaio.com/contracts/ce45492c-0d5f-43d2-b05b-c122bcc71f73"
          },
          "attributes": {
            "title": "contract product A",
            "description": "my contract description",
            "currency": "EUR",
            "created_at": "2017-06-14T14:12:42+00:00"
          }
        },
        {
          "type": "customers",
          "id": "c3ee1056-b650-4403-83ea-580d610cd086",
          "links": {
            "self": "https://api.pagaio.com/customers/c3ee1056-b650-4403-83ea-580d610cd086"
          },
          "attributes": {
            "fullname": "john doe",
            "email": "customer@periodable.com",
            "created_at": "2017-06-15T08:39:09+00:00"
          }
        }
      ]
    }
    

    HTTP Request

    GET https://api.pagaio.com/subscriptions/{id}

    URL attributes

    Name type Description
    id UUID subscription unique identifier

    Retrieve all subscriptions

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/subscriptions'
    
    

    this request will return

    {
      "meta": {
            "page": {
                "first": 1,
                "last": 5,
                "current": 1
            }
        },
        "links": {
            "first": "http://api.pagaio.com/subscriptions?page%5Bnumber%5D=1",
            "last": "http://api.pagaio.com/subscriptions?page%5Bnumber%5D=5",
            "prev": "http://api.pagaio.com/subscriptions?page%5Bnumber%5D=1",
            "next": "http://api.pagaio.com/subscriptions?page%5Bnumber%5D=2",
            "self": "http://api.pagaio.com/subscriptions?page%5Bnumber%5D=1"
        },
        "data": [
        {
            "type": "subscriptions",
            "id": "0002c11e-43a6-441f-b607-51da75820d3c",
            "links": {
                "self": "https://api.pagaio.com/subscriptions/0002c11e-43a6-441f-b607-51da75820d3c"
            },
            "attributes": {
                "status": "ready",
                "created_at": "2017-12-02T06:14:58+00:00",
                "metadata": [],
                "payment_url": "http://test_1.pagaio.com/subscriptions/payments/0002c11e-43a6-441f-b607-51da75820d3c"
            },
            "relationships": {
                "contracts": {
                    "links": {
                        "self": "https://api.pagaio.com/contracts/ce45492c-0d5f-43d2-b05b-c122bcc71f73"
                    },
                    "data": {
                        "type": "contracts",
                        "id": "ce45492c-0d5f-43d2-b05b-c122bcc71f73"
                    }
                },
                "payments": {
                    "links": {
                        "self": "https://api.pagaio.com/payments/cb269e9c-a2b1-49fe-9031-2b257528db32"
                    },
                    "data": {
                        "type": "payments",
                        "id": "cb269e9c-a2b1-49fe-9031-2b257528db32"
                    }
                },
                "customers": {
                    "links": {
                        "self": "https://api.pagaio.com/customers/01e8734b-34f6-4470-a3fa-4576dced2527"
                    },
                    "data": {
                        "type": "customers",
                        "id": "01e8734b-34f6-4470-a3fa-4576dced2527"
                    }
                },
                "subscription_clauses": {
                    "data": [{
                        "type": "subscription_clauses",
                        "id": "ef90b393-13ce-42a1-b8a4-c88a4b74cea3"
                    }, {
                        "type": "subscription_clauses",
                        "id": "9eabd73a-da5b-40e7-8ced-12addf7c40d8"
                    }]
                }
            }
        }, {
            "type": "subscriptions",
            "id": "00d829ed-0301-4dd5-9247-48f962078dcb",
            "links": {
                "self": "https://api.pagaio.com/subscriptions/00d829ed-0301-4dd5-9247-48f962078dcb"
            },
            "attributes": {
                "status": "ready",
                "created_at": "2017-12-02T06:14:57+00:00",
                "metadata": [],
                "payment_url": "http://test_1.pagaio.com/subscriptions/payments/gocardless/00d829ed-0301-4dd5-9247-48f962078dcb"
            },
            "relationships": {
                "contracts": {
                    "links": {
                        "self": "https://api.pagaio.com/contracts/ce45492c-0d5f-43d2-b05b-c122bcc71f73"
                    },
                    "data": {
                        "type": "contracts",
                        "id": "ce45492c-0d5f-43d2-b05b-c122bcc71f73"
                    }
                },
                "payments": {
                    "links": {
                        "self": "https://api.pagaio.com/payments/e1cf527a-6a1e-4582-bf1f-a73712b9e1ec"
                    },
                    "data": {
                        "type": "payments",
                        "id": "e1cf527a-6a1e-4582-bf1f-a73712b9e1ec"
                    }
                },
                "customers": {
                    "links": {
                        "self": "https://api.pagaio.com/customers/adb63bdd-f812-4d2f-8ca1-697a52654e3e"
                    },
                    "data": {
                        "type": "customers",
                        "id": "adb63bdd-f812-4d2f-8ca1-697a52654e3e"
                    }
                },
                "subscription_clauses": {
                    "data": [{
                        "type": "subscription_clauses",
                        "id": "d1752f02-cce9-4c1b-9c89-22041be8c1ca"
                    }, {
                        "type": "subscription_clauses",
                        "id": "2161a327-d51b-4500-958e-7a7feb082597"
                    }]
                }
            }
        }],
        "included": [{
            "type": "contracts",
            "id": "ce45492c-0d5f-43d2-b05b-c122bcc71f73",
            "links": {
                "self": "https://api.pagaio.com/contracts/ce45492c-0d5f-43d2-b05b-c122bcc71f73"
            },
            "attributes": {
                "title": "contract product A",
                "description": "my contract description",
                "currency": "EUR",
                "successful_url": "",
                "cancel_url": "",
                "created_at": "2017-12-02T06:14:57+00:00"
            }
        }, {
            "type": "customers",
            "id": "da105742-42b7-4401-b41f-1c9944c6ccf4",
            "links": {
                "self": "https://api.pagaio.com/customers/da105742-42b7-4401-b41f-1c9944c6ccf4"
            },
            "attributes": {
                "fullname": "john doe",
                "email": "john.doe@pagaio.com",
                "created_at": "2017-12-02T06:14:57+00:00",
                "metadata": []
            }
        }, {
            "type": "subscription_clauses",
            "id": "ef90b393-13ce-42a1-b8a4-c88a4b74cea3",
            "attributes": {
                "type": "first_payment",
                "attributes": [],
                "enabled": true,
                "name": "",
                "description": ""
            }
        }, {
            "type": "subscription_clauses",
            "id": "9eabd73a-da5b-40e7-8ced-12addf7c40d8",
            "attributes": {
                "type": "subscription",
                "attributes": {
                    "price": "9",
                    "recurrence_unit": 1,
                    "recurrence_period": "month"
                },
                "enabled": true,
                "name": "",
                "description": ""
            }
        }, {
            "type": "subscription_clauses",
            "id": "d1752f02-cce9-4c1b-9c89-22041be8c1ca",
            "attributes": {
                "type": "subscription",
                "attributes": {
                    "price": "9",
                    "recurrence_unit": 1,
                    "recurrence_period": "month"
                },
                "enabled": true,
                "name": "",
                "description": ""
            }
        }, {
            "type": "subscription_clauses",
            "id": "2161a327-d51b-4500-958e-7a7feb082597",
            "attributes": {
                "type": "first_payment",
                "attributes": [],
                "enabled": true,
                "name": "",
                "description": ""
            }
        }]
    }
    

    HTTP Request

    GET https://api.pagaio.com/subscriptions?filter[contract_id]={contract_id}&page[number]={number}

    Filters

    It is possible to filter results. For this use the filter query parameter as explain in the json-api documentation. All filters are optional.

    Name type description
    contract_id UUID the contract id to filter. eg: filter[contract_id]=ce45492c-0d5f-43d2-b05b-c122bcc71f73
    customer_id UUID the customer id to filter. eg: filter[customer_id]=da105742-42b7-4401-b41f-1c9944c6ccf4
    customer_email email the customer email to filter. eg filter[customer_email]=contact@pagaio.com

    pagination

    this endpoint is paginated and return 20 items per page. For now it is not possible to change the size. In the query string you can change the page number using the page[number] parameter. In the response you will have several about the pagination. In the meta section you have information about the page number and in the links section you can retrieve several links to navigate between the available pages.

    Close a subscription

    curl --include \
         --request DELETE \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/subscriptions/{id}'
    

    When a subscription is closed, no more payment will be done and all scheduled payment will closed too. It is possible to re-open a closed subscription by adding a new payment method to the subscription.

    closed subscription response

    This endpoint will return a 204 status code and an empty body (according to the 204 status code)

    HTTP Request

    DELETE https://api.pagaio.com/subscriptions/{id}

    URL attributes

    Name type Description
    id UUID subscription unique identifier

    Amendment

    An amendment allow you to modify the subscription's clauses and apply special attributes to your customer. An amendment can also enable or disable a subscription's clause. To know the amendment attributes refer to the clause chapter, they are identical depending the clause type.

    create an amendment

    curl --include \
         --request POST \
         --header "Content-Type: application/vnd.api+json" \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
         --data-binary "{
        \"data\": {
          \"type\": \"amendments\",
          \"id\": \"7d043c0d-7042-46d5-9ec6-9d84a7870679\",
          \"attributes\": {
            \"attributes\": {
              \"price\": 600,
              \"recurrence_unit\": 1,
              \"recurrence_period\": \"month\"
            }
          },
          \"relationships\": {
            \"subscription_clauses\": {
              \"data\": {
                \"type\": \"subscription_clauses\",
                \"id\": \"5e95dc0a-b99f-4993-940d-4a7e6b18675f\"
              }
            }
          }
        }
      }" \
    'https://api.pagaio.com/amendments'
    

    HTTP Request

    POST https://api.pagaio.com/amendments

    Amendment attributes

    You must refer to the clause type you want to amend

    Amendment relationships

    An amendment always amend a subscription_clause entity. These entities are created when a subscription is created. Every contract's clauses are saved as a subscription_clause, they became immutable and the only way to override them is to create an amendment.

    Name type mandatory Description
    type string Yes must be subscription_clauses
    id UUID Yes subscription_clauses unique identifier

    Retrieve an amendment

    curl --include \
         --header "Accept: application/vnd.api+json" \
         --header "Authorization: Bearer {token}" \
      'https://api.pagaio.com/amendments/{id}'
    

    HTTP Request

    GET https://api.pagaio.com/amendments/{id}

    URL attributes

    Name type Description
    id UUID subscription unique identifier