Skip to main content

Recurring Payments: Request examples

A recurring subscription automatically charges the customer at a specified interval (e.g., monthly) until a set end date or the desired number of payments is reached. During subscription creation, you define:

  • Interval quantity and interval type (e.g., every 1 month)
  • End date or number of total payments
  • Card or payment method details

Once the initial payment is completed, the gateway creates a recurring subscription identified by recurringId. You can then manage this subscription (retrieve details, cancel it) through the provided endpoints.

Overview​

  1. Creating a recurring subscription for:
  2. Receiving the recurring subscription ID once the initial payment succeeds
  3. Handling subsequent charges and callbacks
  4. Retrieving recurring subscription details (optional)
  5. Canceling a subscription (optional)
sequenceDiagram
title Recurring Payments (Subscriptions)

participant Merchant
participant PG as Payment Gateway

note over Merchant,PG: Step 1 - Create Recurring Order
Merchant->>PG: Create Order (PCI, Binded Card, or Hosted Page)
activate PG
PG->>Merchant: Return order info + (optional) paymentLink
deactivate PG
note over Merchant,PG: Once payment is successful, subscription is created (recurringId)

note over Merchant,PG: Step 2 - Callback or Check Order Status
PG->>Merchant: Callback/Order Status with recurringId

note over Merchant,PG: Step 3 - Subsequent Charges
activate PG
PG->>Merchant: Callback for each new payment
deactivate PG

opt Retrieve Subscription Details
  Merchant->>PG: Retrieve subscription info (recurringId)
  PG->>Merchant: Return schedule, status, upcoming charges
end

opt Cancel Subscription
  Merchant->>PG: Cancel subscription (recurringId)
  PG->>Merchant: Return "canceled"
end

1. Create a Recurring Subscription​

To create a recurring subscription, you must first create an order that is successfully paid by your customer. Once the payment completes, the subscription is activated automatically. The order is created using the Create Order endpoint.

If you are a PCI DSS merchant who collects card data directly, you can choose either approach (PCI DSS or non-PCI DSS or Binded Card). If you are a non-PCI DSS merchant, you must use the “Non-PCI DSS” or ”Binded Card” approach below.

Only this first step differs for PCI DSS vs. non-PCI DSS merchants. All following steps are the same.

If you are a PCI DSS merchant who collects card data directly from customer on your side, you can create a recurring subscription as shown below. This approach includes sending card data (cardNumber, cvv, etc.) along with the recurring payment configuration.

curl -L 'https://gateway.madfintech.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: <Api-Access-Token>' \
--data-raw '{
  "shopId": 1234,
  "order": {
    "orderNumber": "56573FDFVFDBWF",
    "cost": {
      "amount": "56.99",
      "currency": "USD"
    },
    "recurringPayments": {
      "billingIntervalQuantity": 1,
      "intervalType": "month",
      "endDate": "2025-12-01T14:30:00+03:00",
      "paymentCount": 3
    }
  },
  "customer": {
    "customerId": "56656"
  },
  "paymentSettings": {
    "entryMode": "cnp",
    "instrumentType": "card",
    "providerCode": "someProvider",
    "acquirerCode": "someAcquirer"
  },
  "paymentPageDesign": {
    "format": "shop_hosted"
  },
  "payer": {
    "cardData": {
      "cardId": "94831",
      "cardNumber": "4111111111111111",
      "cardHolderName": "JOHN A DOE",
      "cvv": "010",
      "expireMonth": "12",
      "expireYear": "2023"
    },
    "personalData": {
      "firstName": "John",
      "lastName": "Smith"
    },
    "billingAddress": {
      "addressLine1": "7, Sunny street",
      "countryCode": "CY"
    }
  }
}'
{
  "data": {
    "orderNumber": "56573FDFVFDBWF"
  }
}

2. Callback or Check Order Status to Get recurringId​

When the initial payment has succeeded and the subscription is created, you will receive a callback that includes recurringId under recurringPayments. Alternatively, you can retrieve the order status at any time to check for the recurringId.

curl -L 'https://gateway.madfintech.com/api/v1/order/1234/56573FDFVFDBWF' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: <Api-Access-Token>'
{
  "data": {
    "id": 54222,
    "shopId": 1234,
    "orderNumber": "56573FDFVFDBWF",
    "orderStatus": "in_progress",
    "cost": {
      "amount": "56.99",
      "currency": "USD"
    },
    "recurringPayments": {
      "recurringId": "sub_54222",
      "status": "active"
    },
    "orderCreatedAt": "2023-08-29T15:34:56+03:00",
    "orderPaidAt": "2023-08-29T15:34:56+03:00",
    "autoCapture": true,
    "payments": [
      {
        "paymentId": "79",
        "paymentType": "payment",
        "cost": {
          "amount": "56.99",
          "currency": "USD"
        },
        "acquirer": {
          "code": "someProvider"
        },
        "provider": {
          "code": "someProvider"
        },
        "instrumentType": "card",
        "paymentStatus": {
          "status": "completed"
        },
        "paymentDetails": {
          "paymentSystem": "visa",
          "authCode": "auth94753457343",
          "rrn": "rrn583743856734",
          "maskedCardNumber": "123456******1234"
        },
        "providerPaymentId": "990943",
        "transactionId": "172666307000000001"
      }
    ],
    "customer": {
      "customerId": "56656"
    }
  }
}

3. Subsequent Charges and Callbacks​

For each subsequent interval (e.g., monthly), the gateway automatically attempts to charge the customer. You will receive a callback with a new payment in the payments array whenever a charge is attempted. You can also check the order status endpoint to see updated payment details.

Below is an example of the order data showing multiple payments in the payments array after another successful charge:

{
  "data": {
    "id": 54222,
    "shopId": 1234,
    "orderNumber": "56573FDFVFDBWF",
    "orderStatus": "in_progress",
    "cost": {
      "amount": "56.99",
      "currency": "USD"
    },
    "recurringPayments": {
      "recurringId": "sub_54222",
      "status": "active"
    },
    "orderCreatedAt": "2023-08-29T15:34:56+03:00",
    "orderPaidAt": "2023-08-29T15:34:56+03:00",
    "autoCapture": true,
    "payments": [
      {
        "paymentId": "79",
        "paymentType": "payment",
        "cost": {
          "amount": "56.99",
          "currency": "USD"
        },
        "acquirer": {
          "code": "someProvider"
        },
        "provider": {
          "code": "someProvider"
        },
        "instrumentType": "card",
        "paymentStatus": {
          "status": "completed"
        },
        "paymentDetails": {
          "paymentSystem": "visa",
          "authCode": "auth94753457343",
          "rrn": "rrn583743856734",
          "maskedCardNumber": "123456******1234"
        },
        "providerPaymentId": "990943",
        "transactionId": "172666307000000001"
      },
      {
        "paymentId": "79",
        "paymentType": "payment",
        "cost": {
          "amount": "56.99",
          "currency": "USD"
        },
        "acquirer": {
          "code": "someProvider"
        },
        "provider": {
          "code": "someProvider"
        },
        "instrumentType": "card",
        "paymentStatus": {
          "status": "completed"
        },
        "paymentDetails": {
          "paymentSystem": "visa",
          "authCode": "auth94753457343",
          "rrn": "rrn583743856734",
          "maskedCardNumber": "123456******1234"
        },
        "providerPaymentId": "990943",
        "transactionId": "172666307000000001"
      }
    ],
    "customer": {
      "customerId": "56656"
    }
  }
}

Whenever a renewal payment occurs, this new payment appears under payments.

4. Retrieve Recurring Subscription Details (Optional)​

Use the recurringId to retrieve more information about the subscription: status, schedule, upcoming payments, etc.

curl -L 'https://gateway.madfintech.com/api/v1/recurring/sub_54222' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: <Api-Access-Token>'
{
  "data": {
    "id": "sub_54222",
    "parentId": "????",
    "customerId": "56656",
    "shopId": "1234",
    "orderNumber": "????",
    "intervalType": "month",
    "billingIntervalQuantity": 1,
    "endDate": "2025-12-01T14:30:00+03:00",
    "paymentCount": 3,
    "status": "active",
    "createdAt": "2025-03-18T14:30:00+03:00",
    "cancelledAt": null,
    "failedAt": null,
    "amount": "56.99",
    "currency": "USD",
    "recurringPayments": [
      {
        "chargeDate": "2025-04-01T14:30:00+03:00",
        "endDate": "2025-05-01T14:30:00+03:00",
        "status": "successful"
      },
      {
        "chargeDate": "2025-05-01T14:30:00+03:00",
        "endDate": "2025-06-01T14:30:00+03:00",
        "status": "schedule",
        "tries": []
      },
      {
        "chargeDate": "2025-06-01T14:30:00+03:00",
        "endDate": "2025-07-01T14:30:00+03:00",
        "status": "schedule",
        "tries": []
      }
    ]
  }
}

5. Cancel a Recurring Subscription (Optional)​

If you or the customer wish to stop the recurring plan, you can cancel it at any time. After cancellation, no further charges will occur.

curl -L -X DELETE 'https://gateway.madfintech.com/api/v1/recurring/sub_54222' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: <Api-Access-Token>'
{
  "data": {
    "recurringId": "sub_54222",
    "status": "canceled"
  }
}