# PayPro API Reference Version: v1 ## Servers ``` https://api.paypro.nl ``` ## Security ### apiKey Type: http Scheme: bearer Bearer Format: API key ## Download OpenAPI description [PayPro API Reference](https://docs.paypro.nl/_spec/reference/api.yaml) ## 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](/docs/creating-payments) to see how you can implement payments. ### Retrieves a payment - [GET /payments/{id}](https://docs.paypro.nl/reference/api/payments/retrievepayment.md): Retrieves a single payment based on the id. ### Cancels a payment - [DELETE /payments/{id}](https://docs.paypro.nl/reference/api/payments/cancelpayment.md): Cancels a payment. It is possible to cancel payment only in open or initialiazed state. ### Retrieve a list of payments - [GET /payments](https://docs.paypro.nl/reference/api/payments/retrievelistofpayments.md): Retrieve a list of payments that have been created for your account. The payments are sorted, with the most recent first. ### Creates a payment - [POST /payments](https://docs.paypro.nl/reference/api/payments/createpayment.md): Creates a Payment object. After you have created a Payment you can use the link to redirect your customer. ### Retrieves a list of chargebacks that belong to this payment - [GET /payments/{id}/chargebacks](https://docs.paypro.nl/reference/api/payments/retrievelistofchargebacksbypayment.md): Retrieves a list of chargebacks that belong to this payment. ### Retrieves a list of refunds that belong to this payment. - [GET /payments/{id}/refunds](https://docs.paypro.nl/reference/api/payments/retrievelistofrefundsbypayment.md): Retrieves a list of refunds that belong to this payment. ### Creates a refund for this payment. - [POST /payments/{id}/refunds](https://docs.paypro.nl/reference/api/payments/createrefundforpayment.md): Creates a Refund object for this Payment. Creating a refund will refund a certain amount back to the customer. This amount will be deducted from your balance. You can choose to only refund a part of the total amount. You can do this multiple times, but the total refunded amount can't exceed the payment amount. Some pay methods require additional information, like IBAN and account holder name, to be supplied. ## 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](/docs/refunds) on how to manage and create refunds. ### Retrieves a refund - [GET /refunds/{id}](https://docs.paypro.nl/reference/api/refunds/retrieverefund.md): Retrieves a single refund based on the id. ### Cancels a refund - [DELETE /refunds/{id}](https://docs.paypro.nl/reference/api/refunds/cancelrefund.md): Cancels a refund. It is possible to cancel refund only in open, pending or processing state. ### Retrieve a list of refunds - [GET /refunds](https://docs.paypro.nl/reference/api/refunds/retrievelistofrefunds.md): Retrieve a list of refunds that have been created for your account. The refunds are sorted, with the most recent first ## 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. ### Retrieves a chargeback - [GET /chargebacks/{id}](https://docs.paypro.nl/reference/api/chargebacks/retrievechargeback.md): Retrieves a single chargeback based on the id. ### Retrieve a list of chargebacks - [GET /chargebacks](https://docs.paypro.nl/reference/api/chargebacks/retrievelistofchargebacks.md): Retrieve a list of chargebacks that have been created for your account. The chargebacks are sorted, with the most recent first ## 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. ### Retrieve a list of pay methods - [GET /pay_methods](https://docs.paypro.nl/reference/api/pay-methods/retrievelistofpaymethods.md): Retrieve a list of pay methods. ## 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](/reference/api/customers/createcustomer) 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](/reference/api/mandates), [subscriptions](/reference/api/subscriptions) and [payments](/reference/api/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](/docs/subscriptions). ### Retrieves a customer - [GET /customers/{id}](https://docs.paypro.nl/reference/api/customers/retrievecustomer.md): Retrieves a single customer based on the id. ### Updates a customer - [PATCH /customers/{id}](https://docs.paypro.nl/reference/api/customers/updatecustomer.md): Updates a Customer object. Returns the updated Customer. ### Retrieves a list of customers - [GET /customers](https://docs.paypro.nl/reference/api/customers/retrievelistofcustomers.md): Retrieve a list of customers that have been created for your account. The customers are sorted, with the most recent first. ### Creates a customer - [POST /customers](https://docs.paypro.nl/reference/api/customers/createcustomer.md): Creates a Customer object. ### Retrieves a list of subscriptions that belong to this customer - [GET /customers/{id}/subscriptions](https://docs.paypro.nl/reference/api/customers/retrievelistofsubscriptionsbycustomer.md): Retrieves a list of subscriptions that belong to this customer. ### Retrieves a list of mandates that belong to this customer - [GET /customers/{id}/mandates](https://docs.paypro.nl/reference/api/customers/retrievelistofmandatesbycustomer.md): Retrieves a list of mandates that belong to this customer. ## 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](/docs/recurring-payments) or [Subscriptions guide](/docs/subscriptions) for how to use mandates. ### Retrieves a mandate - [GET /mandates/{id}](https://docs.paypro.nl/reference/api/mandates/retrievemandate.md): Retrieves a single mandate based on the id. ### Retrieve a list of mandates - [GET /mandates](https://docs.paypro.nl/reference/api/mandates/retrievelistofmandates.md): Retrieve a list of mandates that have been created for your account. The mandates are sorted, with the most recent first. ### Creates a mandate - [POST /mandates](https://docs.paypro.nl/reference/api/mandates/createmandate.md): Creates a Mandate object. You can only create a mandate manually for 'direct-debit'. The other supported pay methods require authorization through a Payment. ## 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](/reference/api/subscription-periods) and [Payment](/reference/api/payments) 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](/docs/subscriptions) how to setup and manage your subscriptions. It is also possible to create the [Subscription period](/reference/api/subscription-periods) yourself which we call an "on-demand" subscription check our [On-demand subscriptions guide](/docs/on-demand-subscriptions) how to do this. ### Retrieves a subscription - [GET /subscriptions/{id}](https://docs.paypro.nl/reference/api/subscriptions/retrievesubscription.md): Retrieves a single subscription based on the id. ### Updates a subscription - [PATCH /subscriptions/{id}](https://docs.paypro.nl/reference/api/subscriptions/updatesubscription.md): Updates a Subscription object. Returns the updated Subscription ### Cancels a subscription - [DELETE /subscriptions/{id}](https://docs.paypro.nl/reference/api/subscriptions/cancelsubscription.md): Cancels a subscription. A canceled subscription will no longer create new subscription periods. It is not possible to resume a canceled subscription. ### Retrieves a list of subscriptions - [GET /subscriptions](https://docs.paypro.nl/reference/api/subscriptions/retrievelistofsubscriptions.md): Retrieve a list of subscriptions that have been created for your account. The subscriptions are sorted, with the most recent first. ### Creates a subscription - [POST /subscriptions](https://docs.paypro.nl/reference/api/subscriptions/createsubscription.md): Creates a Subscription object. After you created the subscription it will either be started immediately or at the start_date when a mandate was given. When pay_methods are given you need to redirect the customer to the checkout link in the section. ### Pauses a subscription - [POST /subscriptions/{id}/pause](https://docs.paypro.nl/reference/api/subscriptions/pausesubscription.md): Pauses a subscription. A paused subscription will no longer create new subscription periods. You can resume the subscription by calling the /subscriptions/:id/resume endpoint. ### Resumes a paused subscription - [POST /subscriptions/{id}/resume](https://docs.paypro.nl/reference/api/subscriptions/resumesubscription.md): Resumes a paused subscription. The paused subscription will return to the active state and will resume creating new subscription periods. It is not possible to resume a canceled subscription. ### Retrieves a list subscription periods that belong to this subscription - [GET /subscriptions/{id}/subscription_periods](https://docs.paypro.nl/reference/api/subscriptions/retrievelistofsubscriptionperiodsbysubscription.md): Retrieves a list of subscription periods that belong to this subscription. ### Create a next period for this subscription - [POST /subscriptions/{id}/subscription_periods](https://docs.paypro.nl/reference/api/subscriptions/createsubscriptionperiod.md): Create a next period for this subscription ## Subscription periods The Subscription period represents a period in a [subscription](/reference/api/subscriptions). These are created by the system at the interval you specified or by yourself when using an "on-demand" subscription. The [payment](/reference/api/payments) 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. ### Retrieves a subscription period - [GET /subscription_periods/{id}](https://docs.paypro.nl/reference/api/subscription-periods/retrievesubscriptionperiod.md): Retrieves a single subscription period based on the id. ### Retrieves a list of payments that belong to this subscription period - [GET /subscription_periods/{id}/payments](https://docs.paypro.nl/reference/api/subscription-periods/retrievelistofpaymentsbysubscriptionperiod.md): Retrieves a list of payments that belong to this subscription period. ## 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](/reference/api/subscriptions) first. Most use cases can be solved with subscriptions and installment plans should only be considered if a single invoice is required. ### Retrieves a list of installment plans - [GET /installment_plans](https://docs.paypro.nl/reference/api/installment-plans/retrievelistofinstallmentplans.md): Retrieve a list of installment plans that have been created for your account. The installment plans are sorted, with the most recent first. ### Creates a installment plan - [POST /installment_plans](https://docs.paypro.nl/reference/api/installment-plans/createinstallmentplan.md): 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 section. ### Retrieves a installment plan - [GET /installment_plans/{id}](https://docs.paypro.nl/reference/api/installment-plans/retrieveinstallmentplan.md): Retrieves a single installment plan based on the id. ### Updates an installment plan - [PATCH /installment_plans/{id}](https://docs.paypro.nl/reference/api/installment-plans/updateinstallmentplan.md): Updates an Installment plan object. Returns the updated Installment plan ### Cancels a installment plan - [DELETE /installment_plans/{id}](https://docs.paypro.nl/reference/api/installment-plans/cancelinstallmentplan.md): Cancels a installment plan. A canceled installment plan will no longer create new installment plan periods. It is not possible to resume a canceled installment plan. ### Retrieves a list installment plan periods that belong to this installment plan - [GET /installment_plans/{id}/installment_plan_periods](https://docs.paypro.nl/reference/api/installment-plans/retrievelistofinstallmentplanperiodsbyinstallmentplan.md): Retrieves a list of installment plan periods that belong to this installment plan. ### Pauses a installment plan - [POST /installment_plans/{id}/pause](https://docs.paypro.nl/reference/api/installment-plans/pauseinstallmentplan.md): Pauses a installment plan. A paused installment plan will no longer create new installment plan periods. You can resume the installment plan by calling the /installment_plans/:id/resume endpoint. ### Resumes a paused installment plan - [POST /installment_plans/{id}/resume](https://docs.paypro.nl/reference/api/installment-plans/resumeinstallmentplan.md): Resumes a paused installment plan. The paused installment plan will return to the active state and will resume creating new installment plan periods. It is not possible to resume a canceled installment plan. ## Installment plan periods The Installment plan period represents a period in an [installment plan](/reference/api/installment-plans). These are created by the system at the interval you specified. The [payment](/reference/api/payments) 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. ### Retrieves a installment plan period - [GET /installment_plan_periods/{id}](https://docs.paypro.nl/reference/api/installment-plan-periods/retrieveinstallmentplanperiod.md): Retrieves a single installment plan period based on the id. ### Retrieves a list of payments that belong to this installment plan period - [GET /installment_plan_periods/{id}/payments](https://docs.paypro.nl/reference/api/installment-plan-periods/retrievelistofpaymentsbyinstallmentplanperiod.md): Retrieves a list of payments that belong to this installment plan period. ## 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](/reference/webhooks) system uses these events when sending notifications to your server. Refer to the [webhooks section](/reference/webhooks) for more information. ### Retrieves an event - [GET /events/{id}](https://docs.paypro.nl/reference/api/events/retrieveevent.md): Retrieves a single event based on the id. ### Retrieve a list of events - [GET /events](https://docs.paypro.nl/reference/api/events/retrievelistofevents.md): Retrieve a list of events that have been created for your account. The events are sorted, with the most recent first ## Webhooks Webhooks can be used to send [events](/reference/api/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](https://app.paypro.nl/developers/webhooks). Refer to the [webhooks section](/reference/webhooks) on how to setup and use webhooks and events. ### Retrieves a webhook - [GET /webhooks/{id}](https://docs.paypro.nl/reference/api/webhooks/retrievewebhook.md): Retrieves a single webhook based on the id. ### Updates a webhook - [PATCH /webhooks/{id}](https://docs.paypro.nl/reference/api/webhooks/updatewebhook.md): Updates a Webhook object. Returns the updated Webhook ### Deletes a webhook - [DELETE /webhooks/{id}](https://docs.paypro.nl/reference/api/webhooks/deletewebhook.md): Deletes a webhook. A deleted webhook will no longer send events to the endpoint. ### Retrieves a list of webhooks - [GET /webhooks](https://docs.paypro.nl/reference/api/webhooks/retrievelistofwebhooks.md): Retrieve a list of webhooks that have been created for your account. The webhooks are sorted, with the most recent first. ### Creates a webhook - [POST /webhooks](https://docs.paypro.nl/reference/api/webhooks/createwebhook.md): Creates a Webhook object. A webhook needs to have a , and a . By default the Webhook will be active and subscribed to all event types. You can add the parameter to to make it inactive. ## Balances Balances reflect your PayPro balance. You can retrieve it to see the balances you currently have in your PayPro account. Your account has a balance object per currency. ### Retrieves a balance - [GET /balances/{id}](https://docs.paypro.nl/reference/api/balances/retrievebalance.md): Retrieves a single balance based on the id. ### Retrieve a list of balances - [GET /balances](https://docs.paypro.nl/reference/api/balances/retrievelistofbalances.md): Retrieve a list of balances that are available for your PayPro account. ## 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](/reference/api/payouts/createpayout). When creating a payout you must have sufficient balance in your PayPro account. ### Retrieves a payout - [GET /payouts/{id}](https://docs.paypro.nl/reference/api/payouts/retrievepayout.md): Retrieves a single payout based on the id. ### Retrieve a list of payouts - [GET /payouts](https://docs.paypro.nl/reference/api/payouts/retrievelistofpayouts.md): Retrieve a list of payouts that have been created for your account. The payouts are sorted, with the most recent first. ### Creates a payout - [POST /payouts](https://docs.paypro.nl/reference/api/payouts/createpayout.md): Creates a Payout object. ## 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](/reference/api/top-ups/createtopup). 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. ### Retrieves a top-up - [GET /top_ups/{id}](https://docs.paypro.nl/reference/api/top-ups/retrievetopup.md): Retrieves a single top-up based on the id. ### Retrieve a list of top-ups - [GET /top_ups](https://docs.paypro.nl/reference/api/top-ups/retrievelistoftopups.md): Retrieve a list of top-ups that have been created for your account. The top-ups are sorted, with the most recent first. ### Creates a top-up - [POST /top_ups](https://docs.paypro.nl/reference/api/top-ups/createtopup.md): Creates a Top-up object. After you have created a Top-up you can use the link to redirect to the pay page.