MOmonei
Payments

Recurring Payment

Changed on

Creates a subsequent charge using the payment details from a previous transaction.

This endpoint enables recurring billing and subscription payments by:

  • Using the same payment method as the original payment
  • Charging the customer without requiring them to re-enter payment details
  • Supporting variable or fixed amounts (defaults to the original payment amount if not specified)

Prerequisites:

  1. The initial payment must be created with the sequence parameter
  2. The initial payment will return a sequenceId in the response
  3. This sequenceId must be provided in the URL path when making subsequent recurring charges

Ideal for subscription services, membership renewals, and installment payments.

Need more advanced subscription management? For comprehensive subscription management with features like billing cycles, trial periods, and automatic recurring billing, consider using the Subscriptions API instead. It provides a complete solution for creating and managing subscription-based services.

post/payments/{sequenceId}/recurring

Request

Request body

orderIdstring required

An order ID from your system. A unique identifier that can be used to reconcile the payment with your internal system. Up to 40 characters: ASCII letters, digits and _ @ . / # & + - (no spaces).

amountinteger

Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD).

transactionType'SALE' | 'AUTH' | 'PAYOUT' | 'VERIF'

Controls when the funds will be captured.

descriptionstring

An arbitrary string attached to the payment. Often useful for displaying to users.

callbackUrlstring

The URL to which a payment result should be sent asynchronously.

metadataMetadata

A set of key-value pairs that you can attach to a resource. This can be useful for storing additional information about the resource in a structured format.

Example request

{
  "orderId": "14379133960355",
  "amount": 110,
  "transactionType": "SALE",
  "description": "Test Shop - #84370745531439",
  "customer": {
    "email": "john.doe@example.com",
    "name": "John Doe"
  },
  "billingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "shippingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "callbackUrl": "https://example.com/checkout/callback",
  "metadata": {
    "systemId": "12345"
  }
}

Response

A payment object

idstring required

Unique identifier for the payment.

amountinteger required

Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD).

currencystring required

Three-letter ISO currency code, in uppercase. Must be a supported currency.

orderIdstring

An order ID from your system. A unique identifier that can be used to reconcile the payment with your internal system. Up to 40 characters: ASCII letters, digits and _ @ . / # & + - (no spaces).

descriptionstring

An arbitrary string attached to the payment. Often useful for displaying to users.

accountIdstring required

MONEI Account identifier.

authorizationCodestring

Unique identifier provided by the bank performing transaction.

livemodeboolean required

Has the value true if the resource exists in live mode or the value false if the resource exists in test mode.

status'SUCCEEDED' | 'PENDING' | 'FAILED' | 'CANCELED' | 'REFUNDED' | 'PARTIALLY_REFUNDED' | 'AUTHORIZED' | 'EXPIRED' | 'PENDING_PROCESSING' | 'PAID_OUT' required

The status of the payment.

statusCodestring

Payment status code.

statusMessagestring

Human readable status message, can be displayed to a user.

customerIdstring uuid

The customer this payment belongs to. Linking a payment to a customer saves its payment method under that customer and groups the buyer's payments together.

Not to be confused with paymentMethod.trustly.customerId, which is an identifier Trustly returns for its own account holder and is unrelated.

refundedAmountinteger

Amount in cents refunded (can be less than the amount attribute on the payment if a partial refund was issued).

lastRefundAmountinteger

Amount in cents refunded in the last transaction.

lastRefundReason'duplicated' | 'fraudulent' | 'requested_by_customer' | 'order_canceled'

The reason of the last refund transaction.

cancellationReason'duplicated' | 'fraudulent' | 'requested_by_customer' | 'order_canceled'

The reason for canceling the Payment.

paymentTokenstring

A permanent token represents a payment method used in the payment. Pass generatePaymentToken: true when you creating a payment to generate it. You can pass it as paymentToken parameter to create other payments with the same payment method. This token does not expire, and should only be used server-side.

sequenceIdstring

A permanent identifier that refers to the initial payment of a sequence of payments. This value needs to be sent in the path for RECURRING payments.

storeIdstring

A unique identifier of the Store. If specified the payment is attached to this Store.

pointOfSaleIdstring

A unique identifier of the Point of Sale. If specified the payment is attached to this Point of Sale. If there is a QR code attached to the same Point of Sale, this payment will be available by scanning the QR code.

metadataMetadata

A set of key-value pairs that you can attach to a resource. This can be useful for storing additional information about the resource in a structured format.

createdAtinteger

Time at which the resource was created. Measured in seconds since the Unix epoch.

updatedAtinteger

Time at which the resource updated last time. Measured in seconds since the Unix epoch.

Example response

{
  "id": "af6029f80f5fc73a8ad2753eea0b1be0",
  "amount": 110,
  "currency": "EUR",
  "orderId": "14379133960355",
  "description": "Test Shop - #84370745531439",
  "accountId": "aa9333ba-82de-400c-9ae7-087b9f8d2242",
  "authorizationCode": "475816",
  "status": "PENDING",
  "statusCode": "E000",
  "statusMessage": "Transaction approved",
  "customerId": "a4e1d1dd-e0c2-4f7a-a2b1-2b0f1f9b6b1e",
  "customer": {
    "email": "john.doe@example.com",
    "name": "John Doe"
  },
  "shop": {
    "name": "Test Shop",
    "country": "ES"
  },
  "billingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "shippingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "sessionDetails": {
    "ip": "100.100.200.100",
    "countryCode": "ES",
    "lang": "es",
    "deviceType": "desktop",
    "browser": "Chrome",
    "browserVersion": "83.0.4103.116",
    "os": "Mac OS",
    "osVersion": "10.15.4",
    "source": "MONEI/PHP",
    "sourceVersion": "0.1.2",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
    "browserAccept": "text/html,application/xhtml+xml,application/json",
    "browserColorDepth": "24",
    "browserScreenHeight": "1152",
    "browserScreenWidth": "2048",
    "browserTimezoneOffset": "-120"
  },
  "traceDetails": {
    "ip": "100.100.200.100",
    "countryCode": "ES",
    "lang": "es",
    "deviceType": "desktop",
    "browser": "Chrome",
    "browserVersion": "83.0.4103.116",
    "os": "Mac OS",
    "osVersion": "10.15.4",
    "source": "MONEI/PHP",
    "sourceVersion": "0.1.2",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
    "browserAccept": "text/html,application/xhtml+xml,application/json",
    "browserColorDepth": "24",
    "browserScreenHeight": "1152",
    "browserScreenWidth": "2048",
    "browserTimezoneOffset": "-120",
    "userEmail": "user@example.com"
  },
  "paymentToken": "7cc38b08ff471ccd313ad62b23b9f362b107560b",
  "paymentMethod": {
    "method": "card",
    "card": {
      "country": "ES",
      "brand": "visa",
      "type": "credit",
      "threeDSecureVersion": "2.1.0",
      "threeDSecureFlow": "CHALLENGE",
      "expiration": 2048544000,
      "last4": "0004",
      "fingerprint": "7f2afde1566286c5fb126bb7e79bef549755cce6033dc429013c46d1365ff0e9",
      "tokenizationMethod": "applePay",
      "cardholderName": "John Doe",
      "cardholderEmail": "email@example.com"
    },
    "paypal": {
      "orderId": "7XP21983KL5672104",
      "payerId": "QWRTNBFHZXLPD",
      "email": "john.doe@example.com",
      "name": "John Doe"
    },
    "sepa": {
      "fingerprint": "7f2afde1566286c5fb126bb7e79bef549755cce6033dc429013c46d1365ff0e9"
    },
    "klarna": {
      "billingCategory": "PAY_LATER",
      "authPaymentMethod": "card"
    }
  },
  "sequence": {
    "type": "recurring",
    "recurring": {
      "expiry": "20210630",
      "frequency": 30
    }
  },
  "sequenceId": "62b23b9f3627cc38b08ff471ccd313ad",
  "storeId": "e5f28150d9e8974c58ab5ec9c4a880f8734dcf05",
  "pointOfSaleId": "fb269cccfa0cc021f5d0b8eb1421646c696213e1",
  "metadata": {
    "systemId": "12345"
  },
  "nextAction": {
    "type": "CONFIRM",
    "redirectUrl": "https://secure.monei.com/payments/af6029f80f5fc73a8ad2753eea0b1be0"
  },
  "createdAt": 1636366897,
  "updatedAt": 1636366897
}

Changes

  • 2d67a2ee1e00Revision changes
    • breaking

      the request property's minLength was increased from 0 to 1

    • breaking

      added the pattern ^[a-zA-Z0-9_@./#&+-]{1,40}$ to the request property

    • warning

      the request property's maxLength was set to 40

    • info

      added the optional property to the response with the status

    • info

      the response's property pattern ^[a-zA-Z0-9_@./#&+-]{1,40}$ was added for the status

  • 67c117ca8f44Revision changes
    • warning

      added the new INSTALLMENT_SELECT enum value to the / response property for the response status