Creates a installment plan

Payments

The payment object is the core of the PayPro API. You can create payments to let a customer pay which ultimately transfers funds from them to you.

This allows you to setup one-time payments, recurring payments, subscriptions or invoices.

Refer to our Creating payments guide to see how you can implement payments.

Operations

Refunds

Refunds allow you to return funds to your customer. These funds are deducted from your PayPro balance and are refunded to the card, bank account or wallet used in the initial payment.

You can create refunds yourself or in some cases the customer can initiate a refund.

Refer to our Refund guide on how to manage and create refunds.

Operations

Chargebacks

Chargebacks are created by our system when a customer files a dispute and initiates a chargeback. For example this can happen when the customer does not receive the product bought.

Only certain pay methods have chargebacks like credit card and SEPA Direct Debit. Once the customer initiates a chargeback we will create a chargeback object and notify you through our webhooks.

Operations

Pay methods

Pay method endpoints can be used to retrieve all available payment methods for your account.

The pay method object contains information about the pay method for instance the minimum and maximum amount or which currencies are allowed.

Operations

Customers

Customers are a representation of your customers. These are used to get better insight in your PayPro payments for instance when searching for a customer name in our dashboard.

Customers can be created directly through the API or are created by the system when a payment is paid and no existing customer is associated.

For recurring payments and subscriptions it is mandatory to create a customer. This allows us to manage mandates, subscriptions and payments on the customer level.

A customer does not require any customer information, but we recommend to atleast provide a name or email. This makes it easier to manage your customers and payments in the PayPro dashboard.

To see how you can use customers see our Subscriptions guide.

Operations

Mandates

A Mandate symbolizes the permission the customer gave you to charge their payment method. This is used to setup recurring payments and subscriptions.

Mandates can be created directly for some payment types like "direct-debit" or require an authorization payment which is generally the first payment when setting up the recurring payments or subscription.

Check our Recurring payments guide or Subscriptions guide for how to use mandates.

Operations

Subscriptions

Subscriptions are the easiest way to setup and schedule recurring payments. You provide us the amounts and intervals and PayPro will manage the full life-cycle of the subscription.

Each interval a Subscription period and Payment will be created which will charge the customer.

These subscriptions can be managed through the API or in our dashboard and also includes optional invoicing, debtor management and other features.

Refer to our Subscriptions guide how to setup and manage your subscriptions.

It is also possible to create the Subscription period yourself which we call an "on-demand" subscription check our On-demand subscriptions guide how to do this.

Operations

Subscription periods

The Subscription period represents a period in a subscription. These are created by the system at the interval you specified or by yourself when using an "on-demand" subscription.

The payment created to charge the customer is associated with the subscription period as well as other payments that might happen if the first one fails or when a customer repays after a chargeback.

Operations

Installment plans

Installment plans can be used to periodically charge a customer by specifying the amount and interval. The amount and number of periods are fixed.

The main difference with a subscription is that an installment plan does not run indefinitely and the invoice is generated up front. Where with a subscription it can run indefinitely and an invoice is created for each period.

If you are unsure which to use we suggest to look at the Subscriptions first. Most use cases can be solved with subscriptions and installment plans should only be considered if a single invoice is required.

Operations

Retrieves a list of installment plans

Request

Retrieve a list of installment plans that have been created for your account. The installment plans are sorted, with the most recent first.

Security

apiKey

Responses

installment plans found

Bodyapplication/json

typestringrequired

Value"list"

dataArray of objects(installment_plan)required

Example: [{"id":"PIV1QACRO4DSMQT0KK","type":"installment_plan","description":"Test installment plan","currency":"EUR","installment_plan_type":"direct_debit","state":"active","created_at":"2023-07-24T12:40:10Z","customer":"CU7JRN6W6K3DA9","mandate":"MDC7XX65BH42PW","period":{"amount":"1000","vat":"21","multiplier":1,"interval":"month"},"first_period":{"amount":"1000","vat":"21","multiplier":1,"interval":"month"},"number_of_periods":5,"payment_details":{"return_url":null,"cancel_url":null},"metadata":{},"_links":{"self":"https://api.paypro.nl/installment_plans/PIV1QACRO4DSMQT0KK","customer":"https://api.paypro.nl/customers/CU7JRN6W6K3DA9","mandate":"https://api.paypro.nl/mandates/MDC7XX65BH42PW"}}]

data[].idstringrequired

Example: "PIV1QACRO4DSMQT0KK"

data[].typestringrequired

Value"installment_plan"

Example: "installment_plan"

data[].descriptionstringrequired

Example: "Test installment plan"

data[].installment_plan_typestring or nullrequired

Value"direct_debit"

Example: "direct_debit"

data[].statestringrequired

Example: "active"

data[].currencystringrequired

Value"EUR"

Example: "EUR"

data[].created_atstring(date-time)required

Example: "2023-07-24T12:40:10Z"

data[].customerstring or nullrequired

Example: "CU7JRN6W6K3DA9"

data[].mandatestring or nullrequired

Example: "MDC7XX65BH42PW"

data[].periodobjectrequired

Example: {"amount":"1000","vat":"21","multiplier":1,"interval":"month"}

data[].period.amountintegerrequired

Example: "1000"

data[].period.vatnumber[ 0 .. 100 ]required

Example: "21"

data[].period.multiplierintegerrequired

Example: 1

data[].period.intervalstringrequired

Enum"day""week""month""year"

Example: "month"

data[].first_periodobject or nullrequired

Example: {"amount":"1000","vat":"21","multiplier":1,"interval":"month"}

data[].first_period.amountintegerrequired

Example: "1000"

data[].first_period.vatnumber[ 0 .. 100 ]required

Example: "21"

data[].first_period.multiplierinteger

Example: 1

data[].first_period.intervalstring

Enum"day""week""month""year"

Example: "month"

data[].number_of_periodsnumber>= 1required

Example: 5

data[].payment_detailsobjectrequired

Example: {"return_url":null,"cancel_url":null}

data[].payment_details.return_urlstring or null(uri)required

data[].payment_details.cancel_urlstring or null(uri)required

data[].metadataobjectrequired

Example: {}

data[]._linksobjectrequired

Example: {"self":"https://api.paypro.nl/installment_plans/PIV1QACRO4DSMQT0KK","customer":"https://api.paypro.nl/customers/CU7JRN6W6K3DA9","mandate":"https://api.paypro.nl/mandates/MDC7XX65BH42PW"}

data[]._links.selfstring(uri)required

Example: "https://api.paypro.nl/installment_plans/PIV1QACRO4DSMQT0KK"

data[]._links.customerstring(uri)

Example: "https://api.paypro.nl/customers/CU7JRN6W6K3DA9"

data[]._links.mandatestring(uri)

Example: "https://api.paypro.nl/mandates/MDC7XX65BH42PW"

data[]._links.checkoutstring(uri)

countintegerrequired

_linksobjectrequired

_links.selfstring(uri)required

_links.nextstring(uri)

_links.prevstring(uri)

Response

application/json

{
  "type": "list",
  "data": [
    { … }
  ],
  "count": 0,
  "_links": {
    "self": "http://example.com",
    "next": "http://example.com",
    "prev": "http://example.com"
  }
}

Creates a installment plan

Request

Creates a Installment plan object.

After you have created a Installment plan, it will start immediately when mandate is given. When pay_methods are given you need to redirect the customer to the checkout link in the links section.

Security

apiKey

Bodyapplication/json

customerstringrequired

ID of the customer for installment plan. Cannot be used together with a mandate.

Example: "CUW78XU8BYL8X6"

mandatestring

ID of the mandate for installment plan

descriptionstringrequired

Description of the installment plan. This will be shown to customers

Example: "description"

currencystringrequired

The currency of the installment plan. Only 'EUR' is supported

Example: "EUR"

pay_methodsArray of strings or null

Pay methods that can be used to start the subscription. Using this creates the subscription with the authorization flow and will start the subscription when the first payment is paid. Use the checkout link in the links field to redirect the customer. Cannot be used together with a mandate.

Enum"bancontact""bank-transfer""creditcard""direct-debit""ideal""ideal-qr""klarna-paynow"

Example: ["creditcard","direct-debit","ideal"]

payment_detailsobject

Fields to be passed to the authorization payment.

periodobjectrequired

Settings for when new periods should be created and with which amounts

Example: {"amount":1000,"vat":21,"multiplier":1,"type":"month"}

period.amountinteger

The amount in cents that the customer will have to pay.

Example: 1000

period.vatnumber or null

The vat included in the amount. Accepted values: from 0 till 30

Example: 21

period.intervalstring

The interval of each period. Accepted values: day, week, month or year

period.multiplierinteger

The multiplier of the interval between periods. Example: interval=month and mulitplier=3 will create a new period every 3 months.

Example: 1

first_periodobject or null

Settings for when the first period should be created and with what amount

number_of_periodsintegerrequired

The number of installment plan periods.

Example: 5

metadataobject or null

You can put in random data that you like to save alongside the installment plan. When you fetch the installment plan this will be returned in the metadata field.

Responses

installment plan created

Bodyapplication/json

idstringrequired

Example: "PIV1QACRO4DSMQT0KK"

typestringrequired

Value"installment_plan"

Example: "installment_plan"

descriptionstringrequired

Example: "Test installment plan"

installment_plan_typestring or nullrequired

Value"direct_debit"

Example: "direct_debit"

statestringrequired

Example: "active"

currencystringrequired

Value"EUR"

Example: "EUR"

created_atstring(date-time)required

Example: "2023-07-24T12:40:10Z"

customerstring or nullrequired

Example: "CU7JRN6W6K3DA9"

mandatestring or nullrequired

Example: "MDC7XX65BH42PW"

periodobjectrequired

Example: {"amount":"1000","vat":"21","multiplier":1,"interval":"month"}

period.amountintegerrequired

Example: "1000"

period.vatnumber[ 0 .. 100 ]required

Example: "21"

period.multiplierintegerrequired

Example: 1

period.intervalstringrequired

Enum"day""week""month""year"

Example: "month"

first_periodobject or nullrequired

Example: {"amount":"1000","vat":"21","multiplier":1,"interval":"month"}

first_period.amountintegerrequired

Example: "1000"

first_period.vatnumber[ 0 .. 100 ]required

Example: "21"

first_period.multiplierinteger

Example: 1

first_period.intervalstring

Enum"day""week""month""year"

Example: "month"

number_of_periodsnumber>= 1required

Example: 5

payment_detailsobjectrequired

Example: {"return_url":null,"cancel_url":null}

payment_details.return_urlstring or null(uri)required

payment_details.cancel_urlstring or null(uri)required

metadataobjectrequired

Example: {}

_linksobjectrequired

Example: {"self":"https://api.paypro.nl/installment_plans/PIV1QACRO4DSMQT0KK","customer":"https://api.paypro.nl/customers/CU7JRN6W6K3DA9","mandate":"https://api.paypro.nl/mandates/MDC7XX65BH42PW"}

_links.selfstring(uri)required

Example: "https://api.paypro.nl/installment_plans/PIV1QACRO4DSMQT0KK"

_links.customerstring(uri)

Example: "https://api.paypro.nl/customers/CU7JRN6W6K3DA9"

_links.mandatestring(uri)

Example: "https://api.paypro.nl/mandates/MDC7XX65BH42PW"

_links.checkoutstring(uri)

Response

application/json

{
  "id": "PIV1QACRO4DSMQT0KK",
  "type": "installment_plan",
  "description": "Test installment plan",
  "currency": "EUR",
  "installment_plan_type": "direct_debit",
  "state": "active",
  "created_at": "2023-07-24T12:40:10Z",
  "customer": "CU7JRN6W6K3DA9",
  "mandate": "MDC7XX65BH42PW",
  "period": {
    "amount": "1000",
    "vat": "21",
    "multiplier": 1,
    "interval": "month"
  },
  "first_period": {
    "amount": "1000",
    "vat": "21",
    "multiplier": 1,
    "interval": "month"
  },
  "number_of_periods": 5,
  "payment_details": {
    "return_url": null,
    "cancel_url": null
  },
  "metadata": {},
  "_links": {
    "self": "https://api.paypro.nl/installment_plans/PIV1QACRO4DSMQT0KK",
    "customer": "https://api.paypro.nl/customers/CU7JRN6W6K3DA9",
    "mandate": "https://api.paypro.nl/mandates/MDC7XX65BH42PW"
  }
}

Retrieves a installment plan

Request

Retrieves a single installment plan based on the id.

Security

apiKey

Path

idstringrequired

Responses

installment plan found

Bodyapplication/json

idstringrequired

Example: "PIV1QACRO4DSMQT0KK"

typestringrequired

Value"installment_plan"

Example: "installment_plan"

descriptionstringrequired

Example: "Test installment plan"

installment_plan_typestring or nullrequired

Value"direct_debit"

Example: "direct_debit"

statestringrequired

Example: "active"

currencystringrequired

Value"EUR"

Example: "EUR"

created_atstring(date-time)required

Example: "2023-07-24T12:40:10Z"

customerstring or nullrequired

Example: "CU7JRN6W6K3DA9"

mandatestring or nullrequired

Example: "MDC7XX65BH42PW"

periodobjectrequired

Example: {"amount":"1000","vat":"21","multiplier":1,"interval":"month"}

period.amountintegerrequired

Example: "1000"

period.vatnumber[ 0 .. 100 ]required

Example: "21"

period.multiplierintegerrequired

Example: 1

period.intervalstringrequired

Enum"day""week""month""year"

Example: "month"

first_periodobject or nullrequired

Example: {"amount":"1000","vat":"21","multiplier":1,"interval":"month"}

first_period.amountintegerrequired

Example: "1000"

first_period.vatnumber[ 0 .. 100 ]required

Example: "21"

first_period.multiplierinteger

Example: 1

first_period.intervalstring

Enum"day""week""month""year"

Example: "month"

number_of_periodsnumber>= 1required

Example: 5

payment_detailsobjectrequired

Example: {"return_url":null,"cancel_url":null}

payment_details.return_urlstring or null(uri)required

payment_details.cancel_urlstring or null(uri)required

metadataobjectrequired

Example: {}

_linksobjectrequired

Example: {"self":"https://api.paypro.nl/installment_plans/PIV1QACRO4DSMQT0KK","customer":"https://api.paypro.nl/customers/CU7JRN6W6K3DA9","mandate":"https://api.paypro.nl/mandates/MDC7XX65BH42PW"}

_links.selfstring(uri)required

Example: "https://api.paypro.nl/installment_plans/PIV1QACRO4DSMQT0KK"

_links.customerstring(uri)

Example: "https://api.paypro.nl/customers/CU7JRN6W6K3DA9"

_links.mandatestring(uri)

Example: "https://api.paypro.nl/mandates/MDC7XX65BH42PW"

_links.checkoutstring(uri)

Response

application/json

{
  "id": "PIV1QACRO4DSMQT0KK",
  "type": "installment_plan",
  "description": "Test installment plan",
  "currency": "EUR",
  "installment_plan_type": "direct_debit",
  "state": "active",
  "created_at": "2023-07-24T12:40:10Z",
  "customer": "CU7JRN6W6K3DA9",
  "mandate": "MDC7XX65BH42PW",
  "period": {
    "amount": "1000",
    "vat": "21",
    "multiplier": 1,
    "interval": "month"
  },
  "first_period": {
    "amount": "1000",
    "vat": "21",
    "multiplier": 1,
    "interval": "month"
  },
  "number_of_periods": 5,
  "payment_details": {
    "return_url": null,
    "cancel_url": null
  },
  "metadata": {},
  "_links": {
    "self": "https://api.paypro.nl/installment_plans/PIV1QACRO4DSMQT0KK",
    "customer": "https://api.paypro.nl/customers/CU7JRN6W6K3DA9",
    "mandate": "https://api.paypro.nl/mandates/MDC7XX65BH42PW"
  }
}

Installment plan periods

The Installment plan period represents a period in an installment plan. These are created by the system at the interval you specified.

The payment created to charge the customer are associated with the installment plan period as well as other payments that might happen if the first one fails or when a customer repays after a chargeback.

Operations

Events

Events are generated by our system to notify about something that happened in your account. Events contain an event type like payment.paid or customer.updated and a payload with information about the object for which this event happened.

The event payload always contains the information about the resource at the moment the event was created. This means the information in the payload may be out-of-date. To avoid this you should retrieve the resource from the API again and use the information retrieved in the API request.

You can use these endpoints to retrieve events from your account. Our webhook system uses these events when sending notifications to your server.

Refer to the webhooks section for more information.

Operations

Webhooks

Webhooks can be used to send events to an HTTP endpoint. A typical event is when a payment is paid, payment.paid.

You can retrieve and manage your webhooks through the API or in the PayPro dashboard.

Refer to the webhooks section on how to setup and use webhooks and events.

Operations

Payouts

Payouts are created when you receive funds from PayPro to one of your bank accounts. These can be created on a schedule, through the dashboard or by using the Payout create endpoint.

When creating a payout you must have sufficient balance in your PayPro account.

Operations

Top-ups

Top-ups are a way to top-up your PayPro balance. This can be done through our dashboard or by using the Top-up create endpoint.

The top-up has a unique ID which might be necessary to use when doing manual transfers. When the top-up is processed your PayPro balance will automatically be increased by the amount in the top-up.

Operations

PayPro API Reference (v1)

Payments

Refunds

Chargebacks

Pay methods

Customers

Mandates

Subscriptions

Subscription periods

Installment plans

Retrieves a list of installment plans

Request

Responses

Was this helpful?

Creates a installment plan

Request

Responses

Was this helpful?

Retrieves a installment plan

Request

Responses

Was this helpful?

Installment plan periods

Events

Webhooks

Payouts

Top-ups

PayPro API Reference (v1)

Payments

Refunds

Chargebacks

Pay methods

Customers

Mandates

Subscriptions

Subscription periods

Installment plans

Retrieves a list of installment plans

Request

Responses

Was this helpful?

Creates a installment plan

RequestExpand all

Responses

Was this helpful?

Retrieves a installment plan

Request

Responses

Was this helpful?

Installment plan periods

Events

Webhooks

Payouts

Top-ups

Request