SmartPOS recurring payments allows you to securely store payment details from your terminal, using one of our SmartPOS solutions. This enables quick, easy repeat payments.

For ecommerce solutions, see Recurring payments.

Prerequisites

Have an approved MultiSafepay account.
Set up your terminal and activate it in your MultiSafepay dashboard.
Have the recurring payment feature enabled for your account.

Activation

To activate recurring payments for your account, email [email protected]

Specify in your request which tokenization model(s) you want to use:

Subscriptions
Unscheduled payments

To learn more, see recurring payments .

We send you an agreement to sign, including terms and conditions for data usage.

Supported payment methods

The following payment methods are supported:

Credit/debit cards: Amex, Mastercard, Maestro, Visa, Visa Electron, V Pay.
Wallet: Google Pay, Apple Pay.

Payment flow

Initial payment

The customer gives you consent to store their card details.
MultiSafepay encrypts the payment details during processing and stores them securely on our servers. We return to you a non-sensitive token that references the encrypted payment details.
You can use the token to process recurring payments without needing to handle or store sensitive payment details

This diagram shows a successful payment flow of an initial recurring payment.

Subsequent payments

The customer must give consent (once only).
You include the token in the request to MultiSafepay.
MultiSafepay decrypts the payment details and processes the payment.

This diagram shows a successful payment flow of a subsequent recurring payment.

User guide

Authentication

When processing recurring payments:

Use your device's terminal group API key for the initial payment.
Use a website API key for subsequent payments.

Recurring models

To store customer credentials through tokenization, include the recurring_model parameter in the initial payment request. The following values are supported:

cardOnFile
subscription
unscheduled

Customer token

When processing recurring payments, a token is created and stored. This token is associated to the customer.reference and contains the clients card details. Once an initial payment is created, make a get token request to retrieve the token, and add its value to the recurring_id during the subsequent payment.

Zero Authorization

You can set the amount for the initial payment to 0. No funds are transferred but a token is created. To process payments using zero authorization, enable the feature on your terminal.

To learn more, see Zero Authorization.

How it works

Check how to process recurring payments with your solution:

1. Create an initial payment

Manual input

Prerequisites

Create a QR code with the order details. Add the reference parameter and assign a unique value.
Enable the Insert Order ID feature on your terminal.

Steps

Generate a QR using the JSON object you created with the required parameters as seen in the example below:

   {
   "order_id": "example_order_id",
   "amount": 100,
   "description": "Test description",
   "reference": "customer_example"
   }

In your device's MultiSafepay app, tap Scan QR and scan the generated QR code.
Click Pay and complete the payment process.
The payment is completed and a token will be generated for subsequent payments.

Cloud POS payments

Prerequisites

Add the recurring_model and customer.reference parameters during the order creation.
Enable the Cloud Mode feature on your terminal.

Steps

Create a cloud order . Include the recurring_model and the customer.reference in the request.
Include the terminal_id under gateway_info.
After the order is created, complete the payment process on the terminal.
The payment is completed and token is generated.

Example request

curl --request POST \
     --url 'https://api.multisafepay.com/v1/json/orders?api_key=YOUR_GROUP_API_KEY' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --data '
{
  "type": "redirect",
  "order_id": "order_id_example",
  "gateway": "",
  "currency": "EUR",
  "amount": 100,
  "description": "Example description",
  "recurring_model": "cardOnFile",
  "payment_options": {
    "notification_url": "https://www.example.com/event/notifications",
    "notification_method": "POST"
    },
  "customer": {
      "locale": "nl_NL",
      "phone": "0612345678",
      "email": "[email protected]",
      "reference":"customer_reference"
  },
  "gateway_info": {
          "terminal_id": "00000ABC"
  }
}

Example response

   {
   "success": true,
   "data": {
       "order_id": "WgulytNbJT7IWlt55jXsd_jesses",
       "session_id": "8035RA6PVv3mVF6DI5TSElvd1wrM9rBosic",
       "payment_url": "https://payv2.dev.multisafepay.com/connect/8035RA6PVv3mVF6DI5TSElvd1wrM9rBosic/?lang=en_US",
       "events_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3NTcwNzIxdasdawlmdadydCI6WyJtYnVzOnNlc3Npb24ub3JkZXIiLCJtYnVzOnNlc3Npb24ucXIiXSwicGlkIjoiODAzNVJBNlBWdjNtVkY2REk1VFNFbHZkMXdyTTlyQm9zaWMiLCJzdWIiOiJwciJ9.9PGbZ5-jNyMfeyLrzWUKbfyrrrsu7Nh6-HeYWLHQh8Q",
       "events_stream_url": "https://api.dev.multisafepay.com/events/stream/"
   }
}

App-to-app

Prerequisites

Have an application where you included the intent object and install it on the terminal. You can find more information in our Github repository.
Check the recurring payment section to learn how to initiate recurring payment from your terminal.
Include the recurring_model and customer.reference parameters in your order.

Steps

The customer selects recurring payments in your app.
Create an order from your app. Send the intent with the recurring_model and the customer.reference.
Complete the payment from the MultiSafepay app.
The payment is completed and a token is generated. The customer is redirected to your app.

2. Create a subsequent payment

After the initial payment is created and completed, you can process subsequent payments using the customer's token. This token is tied to the customer.reference.

To create a subsequent payment:

Retrieve your customer's token via a List tokens request.
Use the recurring payment recipe to create an order. Include customer.reference and recurring_id in the request using your customer's token as the value for recurring_id.
The payment is completed and the amount charged.

Example request

curl --request POST \
  --location 'https://api.multisafepay.com/v1/json/orders?api_key={website_api_key}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "type": "direct",
  "order_id": "order_id_example",
  "gateway": "",
  "currency": "EUR",
  "amount": 100,
  "description": "Test Order Description",
  "recurring_id": "{customer_token}",
  "payment_options": {
      "notification_method": "POST",
      "notification_url": "https://testtool.dev.multisafepay.com/client/json-dev/notification?type=notification"
  },
  "customer": {
      "reference": "your_customer_reference"
  }
}'

Example response

{
"success": true,
"data": {
  "amount": 100,
  "amount_refunded": 0,
  "completed": "YYYY-MM-DDTHH:MM:SS",
  "costs": [
    {
      "amount": 0.6,
      "description": "example description costs",
      "transaction_id": 123456,
      "type": "SYSTEM"
    }
  ],
  "created": "YYYY-MM-DDTHH:MM:SS",
  "currency": "EUR",
  "custom_info": null,
  "customer": {
    "address1": null,
    "address2": null,
    "city": null,
    "cocnumber": null,
    "company_name": null,
    "country": null,
    "country_name": null,
    "email": null,
    "first_name": null,
    "house_number": null,
    "last_name": null,
    "locale": "en_US",
    "phone1": null,
    "phone2": null,
    "reference": "Test-Reference_01",
    "state": null,
    "zip_code": null
  },
  "description": "Example description",
  "fastcheckout": "NO",
  "financial_status": "completed",
  "items": {items},
  "modified": "YYYY-MM-DDTHH:MM:SS",
  "order_adjustment": {
    "total_adjustment": "0.00",
    "total_tax": "0.00"
  }, 
  "order_id": "order_id_example",
  "order_total": "10.00",
  "payment_details": {
    "account_holder_name": "John Doe",
    "account_id": null,
    "acquirer_reference_number": "02692416518000005245676",
    "authorization_code": "004567",
    "card_acceptor_id": "123910",
    "card_acceptor_location": "Location",
    "card_acceptor_name": "John Doe",
    "card_entry_mode": "UNKNOWN",
    "card_expiry_date": "MM/YY",
    "card_funding": " ",
    "external_transaction_id": "521901230422",
    "issuer_bin": "89000",
    "last4": "4231",
    "mcc": "1234",
    "recurring_flow": "token",
    "recurring_id": "{customer_token}",
    "recurring_model": "subscription",
    "response_code": "00",
    "scheme_reference_id": "M1231512",
    "type": "VISA"
  },
  "payment_methods": [
    {
      "account_holder_name": "John Doe",
      "amount": 100,
      "card_expiry_date": "MM/YY",
      "currency": "EUR",
      "description": "Example description",
      "external_transaction_id": "521901230422",
      "payment_description": "Visa",
      "status": "completed",
      "type": "VISA"
    }
  ],
  "reason": "Approved",
  "reason_code": "1000",
  "related_transactions": null,
  "status": "completed",
  "transaction_id": 123451235512314,
  "var1": null,
  "var2": null,
  "var3": null
}
}

Updates

Check the table below to learn more about how to receive updates for recurring payments:

Solution	Initial payment
Manual input	To receive order updates, you can: Make a Get order request. Retrieve the details from the response, or Set up a webhook
Cloud and App-to-app	To receive order updates: Subscribe to our event notifications , or Set up a webhook

Solution

Initial payment

Manual input

To receive order updates, you can:

Make a Get order request. Retrieve the details from the response, or
Set up a webhook

Cloud and App-to-app

To receive order updates:

Subscribe to our event notifications , or
Set up a webhook

For subsequent payments, you can use a Webhook or make a Get order request and retrieve the details from the response.