Skip to main content

Subscription

idSubscription-Id (string)required

Unique identifier for the subscription.

Example: 575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa
amountinteger<int32>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).

Example: 110
currencyPayment-Currency (string)

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

Example: EUR
descriptionSubscription-Description (string)

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

Example: MoonMail Monthly Lite
accountIdAccountId (string)required

MONEI Account identifier.

Example: aa9333ba-82de-400c-9ae7-087b9f8d2242
livemodeLivemode (boolean)required

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

Example: false
statusSubscription-Status (string)required

The status of the subscription.

Enum ValueDescription
PENDINGThe subscription has been created but is waiting for initial payment or activation
EXPIREDThe subscription has reached its end date or maximum number of attempts without successful payment
TRIALINGThe subscription is in trial period before the first payment is required
ACTIVEThe subscription is currently active and payments are being processed normally
PAST_DUEThe most recent payment attempt failed but the subscription will retry according to schedule
PAUSEDThe subscription is temporarily suspended and will resume based on pause settings
CANCELEDThe subscription has been permanently terminated and will not process further payments

Possible values: [PENDING, EXPIRED, TRIALING, ACTIVE, PAST_DUE, PAUSED, CANCELED]

Example: PENDING
customer object
emailstring

The customer's email address.

Example: john.doe@example.com
namestring

The customer's full name or business name.

Example: John Doe
phonestring

The customer's phone number in E.164 format.

Example: null
billingDetails object

Billing information associated with the payment method at the time of the transaction.

namestring

The customer's billing full name.

Example: John Doe
emailstring

The customer's billing email address.

Example: john.doe@example.com
phonestring

The customer's billing phone number in E.164 format.

Example: null
companystring

Billing company name.

Example: null
taxIdstring

Company tax ID.

Example: null
address object
countryCountry (string)

Two-letter country code (ISO 3166-1 alpha-2).

Example: ES
citystring

City, district, suburb, town, or village.

Example: Málaga
line1string

Address line 1 (e.g., street, PO Box, or company name).

Example: Fake Street 123
line2string

Address line 2 (e.g., apartment, suite, unit, or building).

Example: null
zipstring

ZIP or postal code.

Example: 1234
statestring

State, county, province, or region.

Example: Málaga
shippingDetails object

Shipping information associated with the payment.

namestring

The shipping customer's full name.

Example: John Doe
emailstring

The shipping customer's email address.

Example: john.doe@example.com
phonestring

The shipping customer's phone number in E.164 format.

Example: null
companystring

Name of the company where the shipment is going.

Example: null
taxIdstring

Company tax ID.

Example: null
address object
countryCountry (string)

Two-letter country code (ISO 3166-1 alpha-2).

Example: ES
citystring

City, district, suburb, town, or village.

Example: Málaga
line1string

Address line 1 (e.g., street, PO Box, or company name).

Example: Fake Street 123
line2string

Address line 2 (e.g., apartment, suite, unit, or building).

Example: null
zipstring

ZIP or postal code.

Example: 1234
statestring

State, county, province, or region.

Example: Málaga
intervalSubscription-Interval (string)required

Subscription interval. The minute and hour intervals are only available in test mode.

Enum ValueDescription
minuteMinutely
hourHourly
dayDaily
weekWeekly
monthMonthly
yearYearly

Possible values: [minute, hour, day, week, month, year]

Example: month
intervalCountinteger<int32>required

Number of intervals between subscription payments.

Example: 1
pauseIntervalCountinteger<int32>

Number of intervals when subscription will be paused before it activates again.

Example: 1
skipIntervalCountinteger<int32>

The number of intervals during which the subscription billing cycle will be skipped without altering the subscription status. This is useful when payment for a specific period is received through different methods.

Example: 1
lastOrderIdPayment-OrderId (string)

An order ID from your system. A unique identifier that can be used to reconcile the payment with your internal system.

Example: 14379133960355
lastPayment object
idPayment-Id (string)

Unique identifier for the payment.

Example: af6029f80f5fc73a8ad2753eea0b1be0
statusPayment-Status (string)

The status of the payment.

Enum ValueDescription
SUCCEEDEDThe payment has been successfully processed and funds have been captured
PENDINGThe payment is being processed and awaiting completion
FAILEDThe payment attempt was unsuccessful
CANCELEDThe payment was canceled before completion
REFUNDEDThe full payment amount has been refunded
PARTIALLY_REFUNDEDOnly a portion of the payment amount has been refunded
AUTHORIZEDThe payment has been authorized but funds have not been captured yet
EXPIREDThe payment has expired without being completed

Possible values: [SUCCEEDED, PENDING, FAILED, CANCELED, REFUNDED, PARTIALLY_REFUNDED, AUTHORIZED, EXPIRED]

Example: PENDING
statusCodePayment-StatusCode (string)

Payment status code.

Example: E000
statusMessagePayment-StatusMessage (string)

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

Example: Transaction approved
paymentMethod object

Details about the payment method at the time of the transaction.

methodstring

Subscription method type.

Enum ValueDescription
cardCard

Possible values: [card]

Example: card
card object

Details about the card used as payment method at the time of the transaction.

countryCountry (string)

Two-letter country code (ISO 3166-1 alpha-2).

Example: ES
brandstring

Card brand.

Enum ValueDescription
visaVisa credit or debit card
mastercardMastercard credit or debit card
dinersDiners Club credit card
amexAmerican Express credit card
jcbJapan Credit Bureau card
unionpayUnionPay card from China
unknownCard brand could not be determined

Possible values: [visa, mastercard, diners, amex, jcb, unionpay, unknown]

Example: visa
typestring

Card type debit or credit.

Possible values: [debit, credit]

Example: credit
threeDSecureboolean

Whether this transaction used 3D Secure authentication.

Example: false
threeDSecureVersionstring

The protocol version of the 3DS challenge.

Example: 2.1.0
threeDSecureFlowstring

The flow used for 3DS authentication.

Enum ValueDescription
CHALLENGEAuthentication requiring additional shopper interaction through biometrics, 2FA, or other SCA methods
FRICTIONLESSBackground authentication using device fingerprint without additional shopper interaction
FRICTIONLESS_CHALLENGEComplete 3DS flow with additional authentication if initial data collection is insufficient
DIRECTTransaction exempt from SCA due to low risk assessment

Possible values: [CHALLENGE, FRICTIONLESS, FRICTIONLESS_CHALLENGE, DIRECT]

Example: CHALLENGE
expirationinteger<int64>

Time at which the card will expire. Measured in seconds since the Unix epoch.

Example: 2048544000
last4string

The last four digits of the card.

Example: 0004
tokenizationMethodstring

The digital wallet used to tokenize the card.

Possible values: [applePay, googlePay, clickToPay]

Example: applePay
cardholderNamestring

The name of the cardholder.

Example: John Doe
cardholderEmailstring

The email of the cardholder.

Example: email@example.com
currentPeriodStartnumber<int64>

The start date of the current subscription period. Measured in seconds since the Unix epoch.

Example: 1636366897
currentPeriodEndnumber<int64>

The end date of the current subscription period. Measured in seconds since the Unix epoch.

Example: 1636366897
trialPeriodEndnumber<int64>

The end date of the trial period. Measured in seconds since the Unix epoch.

Example: 1636366897
nextPaymentAtinteger<int64>

The date when the next payment will be made.

Example: 1636366897
retryCountinteger<int32>

Number of retries left for the subscription.

Example: 1
retrySchedule object[]

Defines a custom schedule for retrying failed subscription payments. Each entry in the array specifies how long to wait before attempting the next payment retry. If not specified, the system's default retry schedule will be used.

  • Array [
    • intervalstringrequired

    The unit of time to wait before the retry attempt.

    Enum ValueDescription
    dayDaily
    weekWeekly
    monthMonthly
    yearYearly

    Possible values: [day, week, month, year]

    Example: day
    intervalCountinteger<int32>required

    The number of intervals to wait before the retry attempt.

    Possible values: >= 1 and <= 31

    Example: 3
  • ]
    • cancelAtPeriodEndSubscription-CancelAtPeriodEnd (boolean)

    If true, the subscription will be canceled at the end of the current period.

    Example: false
    pauseAtPeriodEndSubscription-PauseAtPeriodEnd (boolean)

    If true, the subscription will be paused at the end of the current period.

    Example: false
    traceDetails Payment-TraceDetails

    Information related to the browsing session of the user who initiated the payment.

    ipIP (string)

    The IP address where the operation originated.

    Example: 100.100.200.100
    countryCodeCountry (string)

    Two-letter country code (ISO 3166-1 alpha-2).

    Example: ES
    langLang (string)

    Two-letter language code (ISO 639-1).

    Example: es
    deviceTypeDeviceType (string)

    Device type, could be desktop, mobile, smartTV, tablet.

    Example: desktop
    deviceModelDeviceModel (string)

    Information about the device used for the browser session (e.g., iPhone).

    Example: null
    browserBrowser (string)

    The browser used in this browser session (e.g., Mobile Safari).

    Example: Chrome
    browserVersionBrowserVersion (string)

    The version for the browser session (e.g., 13.1.1).

    Example: 83.0.4103.116
    osOs (string)

    Operation system (e.g., iOS).

    Example: Mac OS
    osVersionOsVersion (string)

    Operation system version (e.g., 13.5.1).

    Example: 10.15.4
    sourceSource (string)

    The source component from where the operation was generated (mostly for our SDK's).

    Example: MONEI/PHP
    sourceVersionSourceVersion (string)

    The source component version from where the operation was generated (mostly for our SDK's).

    Example: 0.1.2
    userAgentUserAgent (string)

    Full user agent string of the browser session.

    Example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...
    browserAcceptBrowserAccept (string)

    Browser accept header.

    Example: text/html,application/xhtml+xml,application/json
    browserColorDepthBrowserColorDepth (string)

    The color depth of the browser session (e.g., 24).

    Example: 24
    browserScreenHeightBrowserScreenHeight (string)

    The screen height of the browser session (e.g., 1152).

    Example: 1152
    browserScreenWidthBrowserScreenWidth (string)

    The screen width of the browser session (e.g., 2048).

    Example: 2048
    browserTimezoneOffsetBrowserTimezoneOffset (string)

    The timezone offset of the browser session (e.g., -120).

    Example: -120
    userIdstring

    The ID of the user that started the operation.

    Example: null
    userEmailstring

    The email of the user that started the operation.

    Example: user@example.com
    sequenceIdPayment-SequenceId (string)

    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.

    Example: 62b23b9f3627cc38b08ff471ccd313ad
    callbackUrlSubscription-CallbackUrl (string)

    The URL will be called each time subscription status changes. You will receive a subscription object in the body of the request.

    Example: https://example.com/subscriptions/callback
    paymentCallbackUrlSubscription-PaymentCallbackUrl (string)

    The URL will be called each time subscription creates a new payments. You will receive the payment object in the body of the request.

    Example: https://example.com/payments/callback
    metadataobject

    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: {"systemId":"12345"}
    createdAtinteger<int64>

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

    Example: 1636366897
    updatedAtinteger<int64>

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

    Example: 1636366897
    Subscription
    {
      "id": "575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa",
      "amount": 110,
      "currency": "EUR",
      "description": "MoonMail Monthly Lite",
      "accountId": "aa9333ba-82de-400c-9ae7-087b9f8d2242",
      "livemode": false,
      "status": "PENDING",
      "customer": {
        "email": "john.doe@example.com",
        "name": "John Doe",
        "phone": null
      },
      "billingDetails": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": null,
        "company": null,
        "taxId": null,
        "address": {
          "country": "ES",
          "city": "Málaga",
          "line1": "Fake Street 123",
          "line2": null,
          "zip": "1234",
          "state": "Málaga"
        }
      },
      "shippingDetails": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": null,
        "company": null,
        "taxId": null,
        "address": {
          "country": "ES",
          "city": "Málaga",
          "line1": "Fake Street 123",
          "line2": null,
          "zip": "1234",
          "state": "Málaga"
        }
      },
      "interval": "month",
      "intervalCount": 1,
      "pauseIntervalCount": 1,
      "skipIntervalCount": 1,
      "lastOrderId": "14379133960355",
      "lastPayment": {
        "id": "af6029f80f5fc73a8ad2753eea0b1be0",
        "status": "PENDING",
        "statusCode": "E000",
        "statusMessage": "Transaction approved"
      },
      "paymentMethod": {
        "method": "card",
        "card": {
          "country": "ES",
          "brand": "visa",
          "type": "credit",
          "threeDSecure": false,
          "threeDSecureVersion": "2.1.0",
          "threeDSecureFlow": "CHALLENGE",
          "expiration": 2048544000,
          "last4": "0004",
          "tokenizationMethod": "applePay",
          "cardholderName": "John Doe",
          "cardholderEmail": "email@example.com"
        }
      },
      "currentPeriodStart": 1636366897,
      "currentPeriodEnd": 1636366897,
      "trialPeriodEnd": 1636366897,
      "nextPaymentAt": 1636366897,
      "retryCount": 1,
      "retrySchedule": [
        {
          "interval": "day",
          "intervalCount": 1
        },
        {
          "interval": "day",
          "intervalCount": 3
        },
        {
          "interval": "week",
          "intervalCount": 1
        }
      ],
      "cancelAtPeriodEnd": false,
      "pauseAtPeriodEnd": false,
      "traceDetails": {
        "ip": "100.100.200.100",
        "countryCode": "ES",
        "lang": "es",
        "deviceType": "desktop",
        "deviceModel": null,
        "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",
        "userId": null,
        "userEmail": "user@example.com"
      },
      "sequenceId": "62b23b9f3627cc38b08ff471ccd313ad",
      "callbackUrl": "https://example.com/subscriptions/callback",
      "paymentCallbackUrl": "https://example.com/payments/callback",
      "metadata": {
        "systemId": "12345"
      },
      "createdAt": 1636366897,
      "updatedAt": 1636366897
    }