Recurring Payments

`POST /v1/payments/card/recurring`

The recurring payment endpoint is used for charging a card regularly (for example, subscriptions
or installment payments). Typically, you would use this after you have already processed an initial payment
with the card (often with 3D Secure if required) or have a token for the card. Recurring payments are usually
merchant-initiated (without direct customer action each time), and may be exempt from 3D Secure
depending on the scenario.

Request Body Parameters

To create a recurring charge, provide the following fields in the JSON body:

Field	Type	Required	Description
`requestId`	String	Yes	Unique ID for this recurring charge request.
`mid`	String	Yes	Merchant account ID.
`token`	String	Yes	The card token represents the customer's saved card (from a prior tokenization or initial payment).
`amount`	String	Yes	Amount to charge for this installment or period, as a string.
`currency`	String	Yes	Currency code for the transaction. ISO 4217 currency code (e.g., `EUR`, `USD`).
`order`	Object (Order Object)	No	Order or subscription details for this charge (e.g., invoice ID, description of the period).
`callbackUrl`	String	No	Webhook URL to receive the transaction result. Recommended since the customer may not be online. Refer to the Webhook Callback Behavior page.
`metadata`	Map<String, String>	No	Additional metadata (e.g., period number, subscription identifiers, etc.).

Unlike one-time charges, successRedirectUrl and failureRedirectUrl are typically not needed for
recurring charges, because the customer is usually not actively waiting on a page to be redirected (these
charges often happen in the background on a schedule).

Similarly, device information is usually not required for recurring payments, as 3D Secure is generally not applied to merchant-initiated recurring transactions (assuming the initial payment was authenticated). Exirom will handle the recurring charge internally and attempt to process it without further customer interaction.

Response

The response for a recurring charge will also include a transactionId and status. In many cases,
recurring charges will be processed immediately as successful or failed without a 3DS challenge. You should
still handle the response and the webhook for the final outcome.

For example:

{
"transactionId": "752609401625775733",
"transactionStatus": "SUCCEED"
}

If the recurring charge fails (e.g., card expired or insufficient funds), you might get:

{
"transactionId": "752609401625775734",
"transactionStatus": "FAILED",
"declineCode": 203
}

Subscription Webhook Callback DTO

When a scheduled charge attempt occurs, Exirom sends a POST request to your configured callbackUrl.

This webhook contains details about the transaction status of the subscription's charge cycle.

Payload Schema

Field	Type	Required	Description
`subscriptionId`	String	Yes	Unique identifier of the subscription plan.
`transactionId`	String	Yes	Unique identifier of the specific charge transaction.
`chargeDate`	String	Yes	ISO 8601 date when the charge attempt occurred (e.g., `2025-09-01`).
`amount`	Number	Yes	Amount attempted in this billing cycle.
`currency`	String	Yes	ISO 4217 currency code (e.g., `EUR`, `USD`).
`transactionStatus`	String	Yes	Status of the transaction: `SUCCEED` or `FAILED`.
`declineCode`	Integer	No	Card network or processor-specific decline code, if the charge failed.
`declineReason`	String	No	Human-readable explanation of the failure, if any.
`failureCount`	Integer	Yes	Number of consecutive failed charge attempts for this subscription.
`nextChargeDate`	String	Yes	ISO 8601 date for the next scheduled retry (e.g., `2025-10-01`).
`metadata`	Map<String, String>	No	Metadata map provided during subscription creation, echoed back in payload.

Example JSON Payload

{
  "subscriptionId":   "sub_3344",
  "transactionId":    "txn9012",
  "chargeDate":       "2025-09-01",
  "amount":           19.99,
  "currency":         "EUR",
  "transactionStatus":"SUCCEED",
  "declineCode":      null,
  "declineReason":    null,
  "failureCount":     0,
  "nextChargeDate":   "2025-10-01",
  "metadata": {
    "subscriptionName": "PremiumPlan",
    "customerId":       "cust-789"
  }
}

💡
Note: After each recurring payment attempt, Exirom will trigger a webhook to your configured callbackUrl.
This ensures your system is notified of every charge event, whether successful or failed.

POST /v1/payments/card/recurring

Request Body Parameters

Response

Subscription Webhook Callback DTO

Payload Schema

Example JSON Payload

Note: After each recurring payment attempt, Exirom will trigger a webhook to your configured callbackUrl.

`POST /v1/payments/card/recurring`

Note: After each recurring payment attempt, Exirom will trigger a webhook to your configured `callbackUrl`.