Direct Starten

Vraag? Stuur ons een bericht

+31 6 26 52 78 57

Wij verwerken online betalingen sinds 2006

Developer Docs

Postbacks

Use postbacks to be notified about events that happen in your PayPro account.

Postbacks, also called webhooks, are a way to communicate between the PayPro servers and your servers. Postbacks are simple POST requests that are sent when events occur in your PayPro account. A merchant has the ability to setup postbacks and listen to these events.

Why use postbacks

Most changes in your account happen asynchronously and do not require an API request to trigger. This creates the problem that there is no way for you to know what happens and when.

Postbacks solve this issue by allowing you to register an URL endpoint that will be notified on new events. PayPro will send POST requests, with relevant data for the type of event that occured to the registered endpoint.

These are some example use cases:

  • Sending an email on a completed payment.
  • Sending a product when a new subscription installment has been paid.
  • Update your backend system with status changes.
  • Check when there are chargebacks for direct debits.

Configuring postbacks

There are two methods for configuring postbacks.

When creating payments

When you use create_payment, create_product_payment or create_invoice you can set the parameter postback_url. This URL will be used for all postbacks for this payment.

# Set `postback_url` to `https://www.mywebshop.nl/postback`
client.params = { postback_url: 'https://www.mywebshop.nl/postback' }

<?
// Set `postback_url` to `https://www.mywebshop.nl/postback`
$client->setParams(["postback_url" => "https://www.mywebshop.nl/postback"]);

# Set `postback_url` to `https://www.mywebshop.nl/postback`
client.setParams({'postback_url': 'https://www.mywebshop.nl/postback'})

User postbacks

If you want to use one single postback URL for your whole account, you can set the postback URL in the PayPro Dashboard settings.

The postback_url parameter in the API call takes precedence over the account settings.

Types of postbacks

There are several types of postbacks you can receive. Each postback type is a different type of event in the PayPro system.

Verkoop

When you create a new payment or subscription there will be a Verkoop postback. This postback contains information about the payment or subscription.

Termijn

The Termijn postback gets sent when a new installment is created for a payment or subscription. For single payments you will only get one, but for subscriptions you can get several.

Termijnstatus

When an installment changes its status, a postback will be sent with the type Termijnstatus. You can use this with subscriptions to check if an installment is already paid.

Factuur

This postback will be sent when you create an invoice.

Pauzeren

When a subscription or recurring payment gets paused, you will receive this postback.

Hervatten

When a subscription or recurring payment is resumed, you will receive this postback.

Annuleren

When a subscription or recurring payment is canceled, you will receive this postback.

Handling postbacks

In order to handle postbacks we need an URL endpoint. This can be a simple file on your server or if you use a framework, you probably need to add a new route/controller to setup an endpoint.

The examples below will only show the postback handling code and not the code to create a page.

# Setup client that we can use later. Use your own API key here.
client = PayPro::Client.new('YOUR_API_KEY')

# params contain the POST variables, like in Rails.

# Postback type is the type of the postback.
type = params[:type]

# Handle different postback types. In this example we handle `Verkoop` and `Termijnstatus` postbacks.
# For `Verkoop` we will show the current payment status.
# For `Termijnstatus` we will show the status of an individual installment from a subscription.
case type
when 'Verkoop'
  # Get the payment hash.
  payment_hash = params[:payment_hash]

  # Use `get_sale` command to get additional information of the payment.
  client.command = 'get_sale'
  client.params = { payment_hash: payment_hash }
  response = client.execute

  # Show the status of the payment.
  puts "Payment has status #{response['current_status']}"
when 'Termijnstatus'
  # Get payment/subscription id.
  id = params[:id]

  # Get the installment number.
  period_number = params[:period_number]

  # Get the installment status.
  status = params[:period_state]

  # Show the status of the installment.
  puts "Installment #{period_number} of subscription #{id} has the status #{status}"
else
  puts "Invalid postback type"
end

<?
// Setup client that we can use later. Use your own API key here.
$client = new \PayPro\Client('YOUR_API_KEY');

// $_POST contains the POST variables.

// Postback type is the type of the postback.
$type = $_POST["type"];

// Handle different postback types. In this example we handle `Verkoop` and `Termijnstatus` postbacks.
// For `Verkoop` we will show the current payment status.
// For `Termijnstatus` we will show the status of an individual installment from a subscription.
switch($type) {
  case 'Verkoop':
    // Get payment hash.
    $payment_hash = $_POST['payment_hash'];

    // Use `get_sale` command to get additional information of the payment.
    $client->setCommand('get_sale');
    $client->setParams(["payment_hash" => $payment_hash]);
    $response = $client->execute();

    // Show the status of the payment.
    echo "Payment hash the status {$response['current_status']}";
    break;
  case 'Termijnstatus':
    // Get payment/subscription id.
    $id = $_POST['id'];

    // Get the installment number.
    $period_number = $_POST['period_number'];

    // Get the installment status.
    $status = $_POST['period_state'];

    // Show the status of the installment
    echo "Installment $period_number of subscription $id has the status $status";
    break;
  default:
    echo "Invalid postback type";
    break;
}

# Setup client that we can use later. Use your own API key here.
client = Client('YOUR_API_KEY')

# Get the POST variables. We use Django in this example.

# Postback type is the type of the postback.
type = request.POST.get('type', '')

# Handle different postback types. In this example we handle `Verkoop` and `Termijnstatus` postbacks.
# For `Verkoop` we will show the current payment status.
# For `Termijnstatus` we will show the status of an individual installment from a subscription.

if type == 'Verkoop':
    # Get the payment hash.
    payment_hash = request.POST.get('payment_hash', '')

    # Use `get_sale` command to get additional information of the payment.
    client.setCommand('get_sale')
    client.setParams({'payment_hash': payment_hash})
    response = client.execute()

    # Show the status of the payment.
    print('Payment has status ' + response['current_status'])
elif type == 'Termijnstatus':
    # Get payment/subscription id.
    id = request.POST.get('id', '')

    # Get the installment number.
    period_number = request.POST.get('period_number', '')

    # Get the installment status.
    status = request.POST.get('period_state', '')

    # Show the status of the installment.
    print('Installment {} of subscription {} has the status {}'.format(period_number, id, status)
else:
  print('Invalid postback type')

Placeholders

The postback URL also allows placeholders to be set. These placeholders will contain information about the payment and will be inserted into the URL when the postback is sent.

The following placeholders are allowed for the postback URL:

  • {CUSTOM} Tracker variable or custom field for the merchant. Will be inserted in the affiliate link.
  • {AMOUNT} Amount of the payment, in cents.
  • {AMOUNT_EURO} Amount of the payment, in euro’s. (500 cents becomes 5.00)
  • {AMOUNT_AFFILIATE} Amount of the affiliate commission, in cents.
  • {AMOUNT_AFFILIATE_EURO} Amount of the affiliate commission, in euro’s. (500 cents becomes 5.00)
  • {NET} Net amount added to the merchant’ account. Only available for merchants.
  • {ID} ID of the payment.

Some examples:

  • https://webshop.nl/postback?custom={CUSTOM}
  • https://webshop.nl/postback/{CUSTOM}
  • https://webshop.nl/postback?amount={AMOUNT}&affiliate_amount={AFFILIATE_AMOUNT}

Guidelines

Using the postback_url parameter.

When using these placeholders with the postback_url parameter, you have to make sure that the query parameters are URL encoded. This means the above examples become:

  • https://webshop.nl/postback?custom=%7BCUSTOM%7D
  • https://webshop.nl/postback/%7BCUSTOM%7D
  • https://webshop.nl/postback?amount=%7BAMOUNT%7D&affiliate_amount=%7BAFFILIATE_AMOUNT%7d

API Reference

Let’s go

Support

Would you like additional support or do you have questions? Contact us.