Breadcrumbs

REST API Recurring payments

Recurring payments, also known as subscription payments are charged automatically to a customer at periodic intervals.

Implementation workflow

You can setup and charge recurring payments with NEXI by following 3 simple steps:

  1. Initial transaction with recurring intent

  2. Store credentials securely

  3. Subsequent recurring transactions

1. Initial transaction

Setup intent for a recurring payment by passing the below information in the credentialOnFile Object: 

{
  ...
  "credentialOnFile": {
    "type": "RECURRING",
    "initialPayment": true,
    "recurring": {
      "frequency": "DAILY", // "WEEKLY"/"MONTHLY"/"YEARLY"
      "startDate": "2025-01-01",
      "expiryDate": "2025-12-01",
      "useCase": "FIXED", // "FLEXIBLE_AMOUNT"/"FLEXIBLE_FREQUENCY"
    }
  }
}


Parameter guide

Parameter

Values

Description

frequency

DAILY/MONTHLY/WEEKLY/YEARLY

Billing cycle frequency

startDate

YYYY-MMM-DD

First charge date

expiryDate

YYYY-MMM-DD

Cancellation date

useCase

FIXED/FLEXIBLE_AMOUNT/FLEXIBLE_FREQUENCY

  • FIXED: Same amount/interval. E.g: subscriptions for SaaS products

  • FLEXIBLE_AMOUNT: Varying charges. E.g: utility payments based on consumption

  • FLEXIBLE_FREQUENCY: Adjustable intervals. E.g: subscriptions with the possibility to change the billing cycles in the course of time.


2. Credential storage

Securely store the credentials based on the integration type upon receiving successful payment response to the initial transaction:

Integration type

Action

Hosted forms – Hosted Payment Page or card Hosted forms

Fetch the pseudoCardNumber by calling Retrieve payment details by payment ID and store it. 

{
  ...
  "paymentMethods": {
    "type": "CARD",
    "card": {
      "cardholderName": "John Doe",
      "pseudoCardNumber": "01234567890124444",
      "first6Digits": 555555,
      "last4Digits": 4444,
      "expiryDate": "01.01.2028",
      "schemeReferenceId": "4234234234",
      ......
      ......
    }
  }
}

Direct Integration

Store either:

  • Clear card data securely that you already have during the payment process.

  • pseudoCardNumber received in payment response if you have the service enabled.

3. Subsequent transactions

Subsequent transactions for an unscheduled MIT should always be sent via the direct integration.

  • Pass the below data in credentialOnFile object for subsequent recurring: 

    {
  ...
  "credentialOnFile": {
    "type": "RECURRING",
    "initialPayment": false,
    "recurring": {
      "frequency": "daily", // "weekly"/"monthly"/"yearly"
      "startDate": "2025-01-01",
      "expiryDate": "2025-12-01",
      "useCase": "FIXED", // "FLEXIBLE_AMOUNT"/"FLEXIBLE_FREQUENCY"
    }
  }
}


  • In addition to the above pass the saved credentials and schemeReferenceId returned previously in the response of initial transaction: 

    {
  ...
  "paymentMethods": {
    "type": "CARD",
    "card": {
      "expiryDate": "202506",
      "cardHolderName": "John Doe",
      "securityCode": "123",
      "number": "5555555555554444", // clear card number or pseudo card number
      "schemeReferenceId": "4234234234"
      .....
      .....
    }
  }
}