{ "openapi": "3.0.0", "info": { "version": "1.8.7", "title": "MONEI API v1", "description": "The MONEI API is organized around REST principles. Our API is designed to be intuitive and developer-friendly.\n\n### Base URL\n\nAll API requests should be made to:\n\n```\nhttps://api.monei.com/v1\n```\n\n### Environment\n\nMONEI provides two environments:\n\n- **Test Environment**: For development and testing without processing real payments\n- **Live Environment**: For processing real transactions in production\n\n### Client Libraries\n\nWe provide official SDKs to simplify integration:\n\n- [PHP SDK](https://github.com/MONEI/monei-php-sdk)\n- [Python SDK](https://github.com/MONEI/monei-python-sdk)\n- [Node.js SDK](https://github.com/MONEI/monei-node-sdk)\n- [Postman Collection](https://postman.monei.com/)\n\nOur SDKs handle authentication, error handling, and request formatting automatically.\n\nYou can download the OpenAPI specification from the https://js.monei.com/api/v1/openapi.json and generate your own client library using the [OpenAPI Generator](https://openapi-generator.tech/).\n\n### Important Requirements\n\n- All API requests must be made over HTTPS\n- If you are not using our official SDKs, you **must provide a valid `User-Agent` header** with each request\n- Requests without proper authentication will return a `401 Unauthorized` error\n\n### Error Handling\n\nThe API returns consistent error codes and messages to help you troubleshoot issues. Each response includes a `statusCode` attribute indicating the outcome of your request.\n\n### Rate Limits\n\nThe API implements rate limiting to ensure stability. If you exceed the limits, requests will return a `429 Too Many Requests` status code.\n" }, "servers": [ { "url": "https://api.monei.com/v1", "description": "MONEI API v1" } ], "security": [ { "APIKey": [] } ], "components": { "securitySchemes": { "APIKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "The MONEI API uses API keys to authenticate requests. Each request must include your API key in the `Authorization` header. You can view and manage your API keys in the [MONEI Dashboard](https://dashboard.monei.com/settings/api). MONEI provides two types of API keys: test mode keys (prefixed with `pk_test_`) and live mode keys (prefixed with `pk_live_`).\n" }, "AccountId": { "type": "apiKey", "in": "header", "name": "MONEI-Account-ID", "description": "If you're integrating with MONEI as a partner or platform, you'll need to use both your Master Account API Key and the Account ID of the merchant you're acting on behalf of. You can find the Account ID for each connected merchant in your [MONEI Partner Dashboard](https://admin.monei.com).\n" } }, "responses": { "BadRequest": { "description": "The request is incorrect or could not be processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "Unauthorized": { "description": "Unauthorized error. Please check your auth credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "NotFound": { "description": "The specified resource was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "InternalServerError": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } }, "ServiceUnavailable": { "description": "The service is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableError" } } } }, "UnprocessableEntity": { "description": "The request was well-formed but could not be processed due to semantic errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntityError" } } } }, "ApplePayCertificateResponse": { "description": "A certificate object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplePayCertificate" } } } }, "ApplePayCertificateListResponse": { "description": "A list of certificates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApplePayCertificate" } } } } }, "DeleteApplePayCertificateResponse": { "description": "A successful deletion response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "RegisterApplePayDomainResponse": { "description": "A successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "ValidateBizumPhoneResponse": { "description": "A successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "isValid" ], "properties": { "isValid": { "type": "boolean", "example": true } } } } } }, "GetPaymentMethodsResponse": { "description": "Available payment methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethods" } } } }, "Payment": { "description": "A payment object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "CreatePosAuthTokenResponse": { "description": "A successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "RS256-signed JWT token for POS authentication. Valid for 24 hours.", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." } } } } } }, "Subscription": { "description": "A subscription object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } } }, "schemas": { "ApiException": { "type": "object", "required": [ "status", "statusCode", "message", "requestId", "requestTime" ], "properties": { "status": { "type": "string", "description": "Error type identifier" }, "statusCode": { "type": "integer", "format": "int32", "description": "HTTP status code" }, "message": { "type": "string", "description": "Human-readable error message" }, "requestId": { "type": "string", "description": "Unique identifier for the request", "example": "df011689-bd3e-4953-95ca-c7bbdacaf6f8" }, "requestTime": { "type": "string", "format": "date-time", "description": "Timestamp when the request was processed", "example": "2025-03-05T10:25:52Z" } } }, "BadRequestError": { "allOf": [ { "$ref": "#/components/schemas/ApiException" }, { "type": "object", "properties": { "status": { "type": "string", "example": "BadRequestError", "description": "Error type identifier" }, "statusCode": { "type": "integer", "format": "int32", "example": 400, "description": "HTTP status code" }, "message": { "type": "string", "example": "Bad request", "description": "Human-readable error message" } } } ] }, "UnauthorizedError": { "allOf": [ { "$ref": "#/components/schemas/ApiException" }, { "type": "object", "properties": { "status": { "type": "string", "example": "UnauthorizedError", "description": "Error type identifier" }, "statusCode": { "type": "integer", "format": "int32", "example": 401, "description": "HTTP status code" }, "message": { "type": "string", "example": "Unauthorized access", "description": "Human-readable error message" } } } ] }, "NotFoundError": { "allOf": [ { "$ref": "#/components/schemas/ApiException" }, { "type": "object", "properties": { "status": { "type": "string", "example": "NotFoundError", "description": "Error type identifier" }, "statusCode": { "type": "integer", "format": "int32", "example": 404, "description": "HTTP status code" }, "message": { "type": "string", "example": "Resource not found", "description": "Human-readable error message" } } } ] }, "InternalServerError": { "allOf": [ { "$ref": "#/components/schemas/ApiException" }, { "type": "object", "properties": { "status": { "type": "string", "example": "InternalServerError", "description": "Error type identifier" }, "statusCode": { "type": "integer", "format": "int32", "example": 500, "description": "HTTP status code" }, "message": { "type": "string", "example": "An unexpected error occurred", "description": "Human-readable error message" } } } ] }, "ServiceUnavailableError": { "allOf": [ { "$ref": "#/components/schemas/ApiException" }, { "type": "object", "properties": { "status": { "type": "string", "example": "ServiceUnavailableError", "description": "Error type identifier" }, "statusCode": { "type": "integer", "format": "int32", "example": 503, "description": "HTTP status code" }, "message": { "type": "string", "example": "Upstream service is unavailable", "description": "Human-readable error message" } } } ] }, "UnprocessableEntityError": { "allOf": [ { "$ref": "#/components/schemas/ApiException" }, { "type": "object", "properties": { "status": { "type": "string", "example": "UnprocessableEntityError", "description": "Error type identifier" }, "statusCode": { "type": "integer", "format": "int32", "example": 422, "description": "HTTP status code" }, "message": { "type": "string", "example": "Unprocessable entity", "description": "Human-readable error message" } } } ] }, "Country": { "type": "string", "example": "ES", "description": "Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2))." }, "IP": { "type": "string", "example": "100.100.200.100", "description": "The IP address where the operation originated." }, "Lang": { "type": "string", "example": "es", "description": "Two-letter language code ([ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1))." }, "DeviceType": { "type": "string", "example": "desktop", "description": "Device type, could be `desktop`, `mobile`, `smartTV`, `tablet`." }, "DeviceModel": { "type": "string", "example": null, "description": "Information about the device used for the browser session (e.g., `iPhone`)." }, "Browser": { "type": "string", "example": "Chrome", "description": "The browser used in this browser session (e.g., `Mobile Safari`)." }, "BrowserVersion": { "type": "string", "example": "83.0.4103.116", "description": "The version for the browser session (e.g., `13.1.1`)." }, "Os": { "type": "string", "example": "Mac OS", "description": "Operation system (e.g., `iOS`)." }, "OsVersion": { "type": "string", "example": "10.15.4", "description": "Operation system version (e.g., `13.5.1`)." }, "Source": { "type": "string", "example": "MONEI/PHP", "description": "The source component from where the operation was generated (mostly for our SDK's)." }, "SourceVersion": { "type": "string", "example": "0.1.2", "description": "The source component version from where the operation was generated (mostly for our SDK's)." }, "UserAgent": { "type": "string", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...", "description": "Full user agent string of the browser session." }, "BrowserAccept": { "type": "string", "example": "text/html,application/xhtml+xml,application/json", "description": "Browser accept header." }, "BrowserColorDepth": { "type": "string", "example": "24", "description": "The color depth of the browser session (e.g., `24`)." }, "BrowserScreenHeight": { "type": "string", "example": "1152", "description": "The screen height of the browser session (e.g., `1152`)." }, "BrowserScreenWidth": { "type": "string", "example": "2048", "description": "The screen width of the browser session (e.g., `2048`)." }, "BrowserTimezoneOffset": { "type": "string", "example": "-120", "description": "The timezone offset of the browser session (e.g., `-120`)." }, "CreatedAt": { "type": "integer", "format": "int64", "example": 1636366897, "description": "Time at which the resource was created. Measured in seconds since the Unix epoch." }, "UpdatedAt": { "type": "integer", "format": "int64", "example": 1636366897, "description": "Time at which the resource updated last time. Measured in seconds since the Unix epoch." }, "Address": { "title": "Address", "type": "object", "properties": { "country": { "$ref": "#/components/schemas/Country" }, "city": { "type": "string", "example": "Málaga", "description": "City, district, suburb, town, or village." }, "line1": { "type": "string", "example": "Fake Street 123", "description": "Address line 1 (e.g., street, PO Box, or company name)." }, "line2": { "type": "string", "example": null, "description": "Address line 2 (e.g., apartment, suite, unit, or building)." }, "zip": { "type": "string", "example": "1234", "description": "ZIP or postal code." }, "state": { "type": "string", "example": "Málaga", "description": "State, county, province, or region." } } }, "CardholderName": { "type": "string", "example": "John Doe", "description": "The cardholder's name, as stated in the credit card." }, "CardholderEmail": { "type": "string", "example": "john.doe@monei.com", "description": "The cardholder's email address." }, "AccountId": { "type": "string", "example": "aa9333ba-82de-400c-9ae7-087b9f8d2242", "description": "MONEI Account identifier." }, "Livemode": { "type": "boolean", "example": false, "description": "Has the value `true` if the resource exists in live mode or the value `false` if the resource exists in test mode." }, "Metadata": { "type": "object", "example": { "systemId": "12345" }, "description": "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." }, "ApplePayCertificate": { "type": "object", "description": "An Apple Pay certificate for iOS app integration.", "properties": { "id": { "type": "string", "description": "Unique identifier of the certificate.", "example": "a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1" }, "accountId": { "type": "string", "description": "The account ID this certificate belongs to.", "example": "acct_12345" }, "csr": { "type": "string", "description": "The Certificate Signing Request in base64 format. Only present before activation. Use this to create a certificate in Apple Developer Portal.", "example": "MIIBEjCBuQIBADBOMRMwE..." }, "cert": { "type": "string", "description": "The certificate body in base64 format. Only present after activation.", "example": "MIIEpDCCA4ygAwIBAgIIU..." }, "active": { "type": "boolean", "description": "Whether the certificate is active for payment processing.", "example": true }, "expireAt": { "type": "string", "format": "date-time", "description": "The certificate expiration date in ISO 8601 format. Only present after activation.", "example": "2026-01-15T12:00:00.000Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "The certificate creation date in ISO 8601 format.", "example": "2024-01-15T12:00:00.000Z" } }, "required": [ "id", "accountId", "active", "createdAt" ] }, "UpdateApplePayCertificateRequest": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Set to true to enable or false to disable the certificate.", "example": true } }, "required": [ "active" ] }, "ActivateApplePayCertificateRequest": { "type": "object", "properties": { "cert": { "type": "string", "description": "The signed certificate from Apple in base64 format. Download this from Apple Developer Portal after creating the certificate with your CSR.", "example": "MIIEpDCCA4ygAwIBAgIIU..." } }, "required": [ "cert" ] }, "RegisterApplePayDomainRequest": { "type": "object", "properties": { "domainName": { "$ref": "#/components/schemas/DomainName" } }, "required": [ "domainName" ] }, "DomainName": { "type": "string", "description": "The domain name to register for Apple Pay.", "example": "example.com" }, "ValidateBizumPhoneRequest": { "type": "object", "required": [ "accountId", "phoneNumber" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "paymentId": { "$ref": "#/components/schemas/Payment-Id" }, "phoneNumber": { "type": "string", "example": "+34500000000", "description": "Phone number in E.164 format." } } }, "PaymentMethods": { "title": "PaymentMethods", "type": "object", "required": [ "livemode", "paymentMethods", "metadata", "merchantName", "merchantUrl", "countryCode" ], "properties": { "livemode": { "$ref": "#/components/schemas/Livemode" }, "paymentMethods": { "$ref": "#/components/schemas/PaymentMethods-Methods" }, "metadata": { "$ref": "#/components/schemas/PaymentMethods-Metadata" }, "merchantName": { "$ref": "#/components/schemas/PaymentMethods-MerchantName" }, "merchantUrl": { "$ref": "#/components/schemas/PaymentMethods-MerchantUrl" }, "countryCode": { "$ref": "#/components/schemas/Country" }, "accountId": { "$ref": "#/components/schemas/AccountId" }, "amount": { "$ref": "#/components/schemas/PaymentMethods-Amount" }, "currency": { "$ref": "#/components/schemas/PaymentMethods-Currency" } } }, "PaymentMethods-Methods": { "type": "array", "items": { "type": "string", "enum": [ "alipay", "applePay", "bancontact", "bizum", "blik", "card", "cardPresent", "clickToPay", "eps", "giropay", "googlePay", "iDeal", "klarna", "mbway", "multibanco", "paypal", "sepa", "sofort", "trustly" ] }, "example": [ "bizum", "applePay", "googlePay", "alipay", "bancontact", "blik", "eps", "iDeal", "mbway", "multibanco", "sofort", "trustly", "sepa", "klarna", "giropay", "card" ], "description": "An array of available payment methods for the account or payment.\nPossible values include:\n - `alipay` - Alipay\n - `applePay` - Apple Pay\n - `bancontact` - Bancontact\n - `bizum` - Bizum\n - `blik` - BLIK\n - `card` - Credit or debit card\n - `cardPresent` - Card present (physical POS)\n - `clickToPay` - Click to Pay\n - `eps` - EPS\n - `giropay` - Giropay\n - `googlePay` - Google Pay\n - `iDeal` - iDEAL\n - `klarna` - Klarna\n - `mbway` - MB WAY\n - `multibanco` - Multibanco\n - `paypal` - PayPal\n - `sepa` - SEPA Direct Debit\n - `sofort` - Sofort\n - `trustly` - Trustly\n" }, "PaymentMethods-Metadata": { "type": "object", "description": "Additional configuration details for each payment method.\n", "properties": { "alipay": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "CN" ], "description": "List of countries where the payment method is available" } } }, "bancontact": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "BE" ], "description": "List of countries where the payment method is available" } } }, "bizum": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "ES" ], "description": "List of countries where the payment method is available" } } }, "blik": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "PL" ], "description": "List of countries where the payment method is available" } } }, "card": { "type": "object", "properties": { "brands": { "type": "array", "items": { "type": "string" }, "example": [ "visa", "mastercard" ], "description": "List of card brands supported" } } }, "eps": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "AT" ], "description": "List of countries where the payment method is available" } } }, "iDeal": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "NL" ], "description": "List of countries where the payment method is available" } } }, "mbway": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "PT" ], "description": "List of countries where the payment method is available" } } }, "multibanco": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "PT" ], "description": "List of countries where the payment method is available" } } }, "sofort": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "AT", "BE", "DE", "ES", "IT", "NL", "CH", "PL" ], "description": "List of countries where the payment method is available" } } }, "trustly": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "DE", "DK", "EE", "ES", "FI", "GB", "LT", "LV", "NL", "NO", "PL", "SE", "SK" ], "description": "List of countries where the payment method is available" } } }, "sepa": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL", "PL", "PT", "RO", "SK", "SI", "ES", "SE", "IS", "LI", "NO", "AD", "SM", "MC", "VA", "PF", "TF", "GI", "GG", "IM", "JE", "BL", "PM", "CH", "GB", "WF" ], "description": "List of countries where the payment method is available" } } }, "klarna": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "AT", "BE", "CH", "DE", "DK", "ES", "FI", "FR", "GB", "IT", "NL", "NO", "SE" ], "description": "List of countries where the payment method is available" } } }, "giropay": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": [ "DE" ], "description": "List of countries where the payment method is available" } } }, "googlePay": { "type": "object", "properties": { "merchantId": { "type": "string", "example": "12345678901234567890", "description": "Google Pay merchant ID" }, "cvcRequired": { "type": "boolean", "example": false, "description": "Whether CVC is required for Google Pay transactions" } } }, "applePay": { "type": "object", "properties": { "merchantId": { "type": "string", "example": "merchant.com.monei", "description": "Apple Pay merchant ID" } } }, "clickToPay": { "type": "object", "properties": { "tokenSupport": { "type": "boolean", "example": true, "description": "Whether token support is enabled" }, "preselected": { "type": "boolean", "example": false, "description": "Whether the method is preselected" }, "visa": { "type": "object", "properties": { "srciDpaId": { "type": "string", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "srcInitiatorId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } }, "mastercard": { "type": "object", "properties": { "srciDpaId": { "type": "string", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "srcInitiatorId": { "type": "string", "example": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11" } } }, "discover": { "type": "object", "properties": { "srciDpaId": { "type": "string", "example": "71f0c4d5-9947-4d1c-9cb3-d6a3f7c4e701" }, "srcInitiatorId": { "type": "string", "example": "c2d06c25-9ddb-4a5e-9d5a-3ff1c8d98467" } } } } } } }, "PaymentMethods-MerchantName": { "type": "string", "example": "MONEI", "description": "The name of the merchant" }, "PaymentMethods-MerchantUrl": { "type": "string", "example": "https://monei.com/", "description": "The URL of the merchant's website" }, "PaymentMethods-Amount": { "type": "integer", "example": 10, "description": "The amount of the payment in the smallest currency unit.\nFor example, 10 EUR = 1000 cents.\nOnly present when querying by paymentId.\n" }, "PaymentMethods-Currency": { "type": "string", "example": "EUR", "description": "Three-letter ISO currency code, in uppercase.\nOnly present when querying by paymentId.\n" }, "Payment": { "title": "Payment", "type": "object", "required": [ "id", "accountId", "amount", "currency", "livemode", "status" ], "properties": { "id": { "$ref": "#/components/schemas/Payment-Id" }, "amount": { "$ref": "#/components/schemas/Payment-Amount" }, "currency": { "$ref": "#/components/schemas/Payment-Currency" }, "orderId": { "$ref": "#/components/schemas/Payment-OrderId" }, "description": { "$ref": "#/components/schemas/Payment-Description" }, "accountId": { "$ref": "#/components/schemas/AccountId" }, "authorizationCode": { "$ref": "#/components/schemas/Payment-AuthorizationCode" }, "livemode": { "$ref": "#/components/schemas/Livemode" }, "status": { "$ref": "#/components/schemas/Payment-Status" }, "statusCode": { "$ref": "#/components/schemas/Payment-StatusCode" }, "statusMessage": { "$ref": "#/components/schemas/Payment-StatusMessage" }, "customer": { "$ref": "#/components/schemas/Payment-Customer" }, "shop": { "$ref": "#/components/schemas/Payment-Shop" }, "billingDetails": { "$ref": "#/components/schemas/Payment-BillingDetails" }, "shippingDetails": { "$ref": "#/components/schemas/Payment-ShippingDetails" }, "refundedAmount": { "$ref": "#/components/schemas/Payment-RefundedAmount" }, "lastRefundAmount": { "$ref": "#/components/schemas/Payment-LastRefundAmount" }, "lastRefundReason": { "$ref": "#/components/schemas/Payment-LastRefundReason" }, "cancellationReason": { "$ref": "#/components/schemas/Payment-CancellationReason" }, "sessionDetails": { "$ref": "#/components/schemas/Payment-SessionDetails" }, "traceDetails": { "$ref": "#/components/schemas/Payment-TraceDetails" }, "paymentToken": { "$ref": "#/components/schemas/Payment-PaymentToken" }, "paymentMethod": { "$ref": "#/components/schemas/Payment-PaymentMethod" }, "sequence": { "$ref": "#/components/schemas/Payment-Sequence" }, "sequenceId": { "$ref": "#/components/schemas/Payment-SequenceId" }, "storeId": { "$ref": "#/components/schemas/Payment-StoreId" }, "pointOfSaleId": { "$ref": "#/components/schemas/Payment-PointOfSaleId" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "nextAction": { "$ref": "#/components/schemas/Payment-NextAction" }, "createdAt": { "$ref": "#/components/schemas/CreatedAt" }, "updatedAt": { "$ref": "#/components/schemas/UpdatedAt" } } }, "CreatePaymentRequest": { "title": "CreatePaymentRequest", "type": "object", "required": [ "amount", "currency", "orderId" ], "properties": { "amount": { "$ref": "#/components/schemas/Payment-Amount" }, "currency": { "$ref": "#/components/schemas/Payment-Currency" }, "orderId": { "$ref": "#/components/schemas/Payment-OrderId" }, "callbackUrl": { "$ref": "#/components/schemas/Payment-CallbackUrl" }, "completeUrl": { "$ref": "#/components/schemas/Payment-CompleteUrl" }, "failUrl": { "$ref": "#/components/schemas/Payment-FailUrl" }, "cancelUrl": { "$ref": "#/components/schemas/Payment-CancelUrl" }, "paymentToken": { "allOf": [ { "$ref": "#/components/schemas/Payment-PaymentToken" } ], "description": "A payment token generated by monei.js\n[Components](https://docs.monei.com/monei-js/overview/) or a paymentToken\n[saved after a previous successful payment](https://docs.monei.com/guides/save-payment-method/).\nIn case of the first one, you will also need to send the `sessionId`\nused to generate the token in the first place.\n" }, "sessionId": { "$ref": "#/components/schemas/Payment-SessionId" }, "generatePaymentToken": { "$ref": "#/components/schemas/Payment-GeneratePaymentToken" }, "paymentMethod": { "$ref": "#/components/schemas/Payment-PaymentMethodInput" }, "allowedPaymentMethods": { "$ref": "#/components/schemas/Payment-PaymentMethods" }, "transactionType": { "$ref": "#/components/schemas/Payment-TransactionType" }, "sequence": { "$ref": "#/components/schemas/Payment-Sequence" }, "storeId": { "$ref": "#/components/schemas/Payment-StoreId" }, "pointOfSaleId": { "$ref": "#/components/schemas/Payment-PointOfSaleId" }, "subscriptionId": { "$ref": "#/components/schemas/Payment-SubscriptionId" }, "autoRecover": { "$ref": "#/components/schemas/Payment-AutoRecover" }, "description": { "$ref": "#/components/schemas/Payment-Description" }, "customer": { "$ref": "#/components/schemas/Payment-Customer" }, "billingDetails": { "$ref": "#/components/schemas/Payment-BillingDetails" }, "shippingDetails": { "$ref": "#/components/schemas/Payment-ShippingDetails" }, "sessionDetails": { "$ref": "#/components/schemas/Payment-SessionDetails" }, "expireAt": { "$ref": "#/components/schemas/Payment-ExpireAt" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ConfirmPaymentRequest": { "title": "ConfirmPaymentRequest", "type": "object", "required": [ "paymentToken" ], "properties": { "paymentToken": { "allOf": [ { "$ref": "#/components/schemas/Payment-PaymentToken" } ], "description": "A payment token generated by monei.js\n[Components](https://docs.monei.com/monei-js/overview/) or a paymentToken\n[saved after a previous successful payment](https://docs.monei.com/guides/save-payment-method/).\n" }, "paymentMethod": { "type": "object", "description": "Additional information about the payment method used for this payment.", "properties": { "card": { "type": "object", "description": "Additional information about the card used for this payment.", "properties": { "cardholderName": { "$ref": "#/components/schemas/CardholderName" }, "cardholderEmail": { "$ref": "#/components/schemas/CardholderEmail" } } } } }, "generatePaymentToken": { "$ref": "#/components/schemas/Payment-GeneratePaymentToken" }, "customer": { "$ref": "#/components/schemas/Payment-Customer" }, "billingDetails": { "$ref": "#/components/schemas/Payment-BillingDetails" }, "shippingDetails": { "$ref": "#/components/schemas/Payment-ShippingDetails" }, "sessionDetails": { "$ref": "#/components/schemas/Payment-SessionDetails" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "CapturePaymentRequest": { "title": "CapturePaymentRequest", "type": "object", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Payment-Amount" } ], "description": "The amount to capture, which must be less than or equal to the\noriginal amount. Any additional amount will be automatically refunded.\n" } } }, "CancelPaymentRequest": { "title": "CancelPaymentRequest", "type": "object", "properties": { "cancellationReason": { "$ref": "#/components/schemas/Payment-CancellationReason" } } }, "RefundPaymentRequest": { "title": "RefundPaymentRequest", "type": "object", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Payment-Amount" } ], "description": "The amount to refund, which must be less than or\nequal to the original amount.\n" }, "refundReason": { "$ref": "#/components/schemas/Payment-RefundReason" } } }, "RecurringPaymentRequest": { "title": "RecurringPaymentRequest", "type": "object", "required": [ "orderId" ], "properties": { "orderId": { "$ref": "#/components/schemas/Payment-OrderId" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Payment-Amount" } ], "description": "The amount to collected by this subsequent payment. A positive integer\nrepresenting how much to charge in the smallest currency unit (e.g.,\n100 cents to charge 1.00 USD).\n" }, "transactionType": { "allOf": [ { "$ref": "#/components/schemas/Payment-TransactionType" } ], "default": "(same as initial payment)", "description": "Same as the `transactionType` parameter from\n[create payment](https://docs.monei.com/apis/rest/payments-create/).\nIf not sent, it will default in the same transaction type used in the initial payment.\n" }, "description": { "$ref": "#/components/schemas/Payment-Description" }, "customer": { "$ref": "#/components/schemas/Payment-Customer" }, "billingDetails": { "$ref": "#/components/schemas/Payment-BillingDetails" }, "shippingDetails": { "$ref": "#/components/schemas/Payment-ShippingDetails" }, "callbackUrl": { "$ref": "#/components/schemas/Payment-CallbackUrl" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "SendPaymentRequestRequest": { "title": "SendPaymentRequestRequest", "type": "object", "required": [ "phoneNumber" ], "properties": { "phoneNumber": { "type": "string", "example": "+34500000000", "description": "Phone number in E.164 format. The customer will receive payment link on this phone number." }, "language": { "$ref": "#/components/schemas/Payment-MessageLanguage" } } }, "SendPaymentLinkRequest": { "title": "SendPaymentLinkRequest", "type": "object", "properties": { "customerEmail": { "type": "string", "example": "john.doe@example.com", "description": "The customer will receive payment link on this email address." }, "customerPhone": { "type": "string", "example": "+34500000000", "description": "Phone number in E.164 format. The customer will receive payment link on this phone number." }, "channel": { "$ref": "#/components/schemas/Payment-MessageChannel" }, "language": { "$ref": "#/components/schemas/Payment-MessageLanguage" } } }, "SendPaymentReceiptRequest": { "title": "SendPaymentReceiptRequest", "type": "object", "properties": { "customerEmail": { "type": "string", "example": "john.doe@example.com", "description": "The customer will receive payment receipt on this email address." }, "customerPhone": { "type": "string", "example": "+34500000000", "description": "Phone number in E.164 format. The customer will receive payment receipt link on this phone number." }, "channel": { "$ref": "#/components/schemas/Payment-MessageChannel" }, "language": { "$ref": "#/components/schemas/Payment-MessageLanguage" } } }, "Payment-Id": { "type": "string", "example": "af6029f80f5fc73a8ad2753eea0b1be0", "description": "Unique identifier for the payment." }, "Payment-Amount": { "type": "integer", "format": "int32", "example": 110, "description": "Amount intended to be collected by this payment. A positive integer\nrepresenting how much to charge in the smallest currency unit (e.g.,\n100 cents to charge 1.00 USD).\n" }, "Payment-Currency": { "type": "string", "example": "EUR", "description": "Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217),\nin uppercase. Must be a supported currency.\n" }, "Payment-OrderId": { "type": "string", "example": "14379133960355", "description": "An order ID from your system. A unique identifier that can be used\nto reconcile the payment with your internal system.\n" }, "Payment-Description": { "type": "string", "example": "Test Shop - #84370745531439", "description": "An arbitrary string attached to the payment. Often useful for\ndisplaying to users.\n" }, "Payment-AuthorizationCode": { "type": "string", "example": "475816", "description": "Unique identifier provided by the bank performing transaction.\n" }, "Payment-Status": { "type": "string", "example": "PENDING", "enum": [ "SUCCEEDED", "PENDING", "FAILED", "CANCELED", "REFUNDED", "PARTIALLY_REFUNDED", "AUTHORIZED", "EXPIRED" ], "x-enumDescriptions": { "SUCCEEDED": "The payment has been successfully processed and funds have been captured", "PENDING": "The payment is being processed and awaiting completion", "FAILED": "The payment attempt was unsuccessful", "CANCELED": "The payment was canceled before completion", "REFUNDED": "The full payment amount has been refunded", "PARTIALLY_REFUNDED": "Only a portion of the payment amount has been refunded", "AUTHORIZED": "The payment has been authorized but funds have not been captured yet", "EXPIRED": "The payment has expired without being completed" }, "description": "The status of the payment." }, "Payment-StatusCode": { "type": "string", "example": "E000", "description": "Payment status code.\n" }, "Payment-StatusMessage": { "type": "string", "example": "Transaction approved", "description": "Human readable status message, can be displayed to a user.\n" }, "Payment-RefundedAmount": { "type": "integer", "format": "int32", "example": null, "description": "Amount in cents refunded (can be less than the amount\nattribute on the payment if a partial refund was issued).\n" }, "Payment-LastRefundAmount": { "type": "integer", "format": "int32", "example": null, "description": "Amount in cents refunded in the last transaction." }, "Payment-LastRefundReason": { "type": "string", "example": null, "enum": [ "duplicated", "fraudulent", "requested_by_customer" ], "description": "The reason of the last refund transaction." }, "Payment-CancellationReason": { "type": "string", "example": null, "enum": [ "duplicated", "fraudulent", "requested_by_customer" ], "description": "The reason for canceling the Payment." }, "Payment-Customer": { "type": "object", "properties": { "email": { "type": "string", "example": "john.doe@example.com", "description": "The customer's email address." }, "name": { "type": "string", "example": "John Doe", "description": "The customer's full name or business name." }, "phone": { "type": "string", "example": null, "description": "The customer's phone number in E.164 format." } } }, "Payment-SessionId": { "type": "string", "example": "39603551437913", "description": "A unique identifier within your system that adds security to the\npayment process. You need to pass the same session ID as the one\nused on the frontend to initialize MONEI Component (if you needed to).\nThis is required if a payment token (not permanent) was already\ngenerated in the frontend.\n" }, "Payment-SequenceId": { "type": "string", "example": "62b23b9f3627cc38b08ff471ccd313ad", "description": "A permanent identifier that refers to the initial payment of\na sequence of payments. This value needs to be sent in the path\nfor `RECURRING` payments.\n" }, "Payment-Sequence": { "type": "object", "description": "This field needs to be sent in order to mark the beginning of a sequence of payments\n(recurring/subscriptions, installments, and so). Specific configurations can be set\nin the inside properties (`recurring`).\n", "required": [ "type" ], "properties": { "type": { "type": "string", "example": "recurring", "enum": [ "recurring" ] }, "recurring": { "$ref": "#/components/schemas/Payment-SequenceRecurring" } } }, "Payment-SequenceRecurring": { "type": "object", "description": "Specific configurations for recurring payments.\nWill only be used when `sequence`.`type` is `recurring`.\n", "properties": { "expiry": { "type": "string", "example": "20210630", "default": "*(The payment method or card expiration)*", "description": "Date after which no further recurring payments will be performed.\nMust be formatted as `YYYYMMDD`.\n" }, "frequency": { "type": "integer", "format": "int32", "example": 30, "default": 25, "description": "The minimum number of **days** between the different recurring payments.\n" } } }, "Payment-PaymentToken": { "type": "string", "example": "7cc38b08ff471ccd313ad62b23b9f362b107560b", "description": "A permanent token represents a payment method used in the\npayment. Pass `generatePaymentToken: true` when you creating\na payment to generate it. You can pass it as `paymentToken`\nparameter to create other payments with the same payment\nmethod. This token does not expire, and should only be\nused server-side.\n" }, "Payment-GeneratePaymentToken": { "type": "boolean", "example": false, "default": false, "description": "If set to true a permanent token that represents a payment\nmethod used in the payment will be generated.\n" }, "Payment-PaymentMethod": { "type": "object", "description": "Details about the payment method at the time of the transaction.\n", "properties": { "method": { "type": "string", "example": "card", "enum": [ "alipay", "card", "bizum", "paypal", "mbway", "multibanco", "iDeal", "bancontact", "sofort", "trustly", "sepa", "klarna", "giropay", "eps", "blik" ], "x-enumDescriptions": { "alipay": "Alipay", "card": "Card", "bizum": "Bizum", "paypal": "PayPal", "mbway": "MB WAY", "multibanco": "Multibanco", "iDeal": "iDEAL", "bancontact": "Bancontact", "sofort": "SOFORT", "trustly": "Trustly", "sepa": "SEPA", "klarna": "Klarna", "giropay": "Giropay", "eps": "EPS", "blik": "BLIK" }, "description": "Payment method type." }, "card": { "$ref": "#/components/schemas/Payment-PaymentMethodCard" }, "bizum": { "$ref": "#/components/schemas/Payment-PaymentMethodBizum" }, "paypal": { "$ref": "#/components/schemas/Payment-PaymentMethodPaypal" }, "mbway": { "$ref": "#/components/schemas/Payment-PaymentMethodMbway" }, "trustly": { "$ref": "#/components/schemas/Payment-PaymentMethodTrustly" }, "sepa": { "$ref": "#/components/schemas/Payment-PaymentMethodSepa" }, "klarna": { "$ref": "#/components/schemas/Payment-PaymentMethodKlarna" } } }, "Payment-PaymentMethodCard": { "type": "object", "description": "Details about the card used as payment method at the time of the transaction.\n", "properties": { "country": { "$ref": "#/components/schemas/Country" }, "brand": { "type": "string", "example": "visa", "enum": [ "visa", "mastercard", "diners", "amex", "jcb", "unionpay", "unknown" ], "x-enumDescriptions": { "visa": "Visa credit or debit card", "mastercard": "Mastercard credit or debit card", "diners": "Diners Club credit card", "amex": "American Express credit card", "jcb": "Japan Credit Bureau card", "unionpay": "UnionPay card from China", "unknown": "Card brand could not be determined" }, "description": "Card brand." }, "type": { "type": "string", "example": "credit", "enum": [ "debit", "credit" ], "description": "Card type `debit` or `credit`." }, "threeDSecure": { "type": "boolean", "example": false, "description": "Whether this transaction used 3D Secure authentication." }, "threeDSecureVersion": { "type": "string", "example": "2.1.0", "description": "The protocol version of the 3DS challenge." }, "threeDSecureFlow": { "type": "string", "example": "CHALLENGE", "enum": [ "CHALLENGE", "FRICTIONLESS", "FRICTIONLESS_CHALLENGE", "DIRECT" ], "x-enumDescriptions": { "CHALLENGE": "Authentication requiring additional shopper interaction through biometrics, 2FA, or other SCA methods", "FRICTIONLESS": "Background authentication using device fingerprint without additional shopper interaction", "FRICTIONLESS_CHALLENGE": "Complete 3DS flow with additional authentication if initial data collection is insufficient", "DIRECT": "Transaction exempt from SCA due to low risk assessment" }, "description": "The flow used for 3DS authentication.\n" }, "expiration": { "type": "integer", "format": "int64", "example": 2048544000, "description": "Time at which the card will expire.\nMeasured in seconds since the Unix epoch.\n" }, "last4": { "type": "string", "example": "0004", "description": "The last four digits of the card." }, "fingerprint": { "type": "string", "example": "7f2afde1566286c5fb126bb7e79bef549755cce6033dc429013c46d1365ff0e9", "description": "Unique identifier for the card number.\nUsed to detect duplicate payment methods across customers.\nNot present for tokenized cards.\n" }, "tokenizationMethod": { "type": "string", "example": "applePay", "enum": [ "applePay", "googlePay", "clickToPay" ], "description": "The digital wallet used to tokenize the card." }, "cardholderName": { "type": "string", "example": "John Doe", "description": "The name of the cardholder." }, "cardholderEmail": { "type": "string", "example": "email@example.com", "description": "The email of the cardholder." } } }, "Payment-PaymentMethodBizum": { "type": "object", "description": "Details about the Bizum account used as payment method at the time of the transaction.\n", "properties": { "phoneNumber": { "type": "string", "example": null, "description": "Phone number in E.164 format used to pay with `bizum`." } } }, "Payment-PaymentMethodPaypal": { "type": "object", "description": "Details from Paypal order used as payment method at the time of the transaction.\n", "properties": { "orderId": { "type": "string", "example": "7XP21983KL5672104", "description": "The Paypal's order ID." }, "payerId": { "type": "string", "example": "QWRTNBFHZXLPD", "description": "The Paypal's payer ID." }, "email": { "type": "string", "example": "john.doe@example.com", "description": "The Paypal's payer email." }, "name": { "type": "string", "example": "John Doe", "description": "The Paypal's payer name." } } }, "Payment-PaymentMethodMbway": { "type": "object", "description": "Details from MBWay order used as payment method at the time of the transaction.\n", "properties": { "phoneNumber": { "type": "string", "example": null, "description": "Phone number in E.164 format used to pay with `mbway`." } } }, "Payment-PaymentMethodSepa": { "type": "object", "description": "Details from SEPA order used as payment method at the time of the transaction.\n", "properties": { "accountholderAddress": { "type": "string", "example": null, "description": "The address of the account holder." }, "accountholderEmail": { "type": "string", "example": null, "description": "The email of the account holder." }, "accountholderName": { "type": "string", "example": null, "description": "The name of the account holder." }, "countryCode": { "type": "string", "example": null, "description": "The country code of the account holder." }, "bankAddress": { "type": "string", "example": null, "description": "The address of the bank." }, "bankCode": { "type": "string", "example": null, "description": "The code of the bank." }, "bankName": { "type": "string", "example": null, "description": "The name of the bank." }, "bic": { "type": "string", "example": null, "description": "The BIC of the bank." }, "last4": { "type": "string", "example": null, "description": "The last 4 digits of the IBAN." }, "fingerprint": { "type": "string", "example": "7f2afde1566286c5fb126bb7e79bef549755cce6033dc429013c46d1365ff0e9", "description": "Unique identifier for the IBAN.\nUsed to detect duplicate payment methods across customers.\n" } } }, "Payment-PaymentMethodTrustly": { "type": "object", "description": "Details from Trustly order used as payment method at the time of the transaction.\n", "properties": { "customerId": { "type": "string", "example": null, "description": "The Trustly's customer ID." } } }, "Payment-PaymentMethodKlarna": { "type": "object", "description": "Details from Klarna order used as payment method at the time of the transaction.\n", "properties": { "billingCategory": { "type": "string", "example": "PAY_LATER", "enum": [ "PAY_LATER", "PAY_NOW", "SLICE_IT", "SLICE_IT_BY_CARD" ], "x-enumDescriptions": { "PAY_LATER": "Pay after delivery within a specified timeframe", "PAY_NOW": "Immediate payment at time of purchase", "SLICE_IT": "Split payment into installments", "SLICE_IT_BY_CARD": "Split payment into installments using a card" } }, "authPaymentMethod": { "type": "string", "example": "card", "enum": [ "invoice", "fixed_amount", "pix", "base_account", "deferred_interest", "direct_debit", "direct_bank_transfer", "b2b_invoice", "card", "slice_it_by_card" ], "x-enumDescriptions": { "invoice": "Traditional invoice payment", "fixed_amount": "Payment with a predetermined fixed amount", "pix": "Brazilian instant payment system", "base_account": "Payment from a basic account", "deferred_interest": "Payment with delayed interest charges", "direct_debit": "Direct bank account debit", "direct_bank_transfer": "Immediate bank transfer", "b2b_invoice": "Business-to-business invoice payment", "card": "Credit or debit card payment", "slice_it_by_card": "Installment payment using a card" } } } }, "Payment-PaymentMethodCardInput": { "type": "object", "description": "Details about the card used as payment method.\nIf provided, MONEI will try to confirm the payment directly.\n", "properties": { "number": { "type": "string", "description": "The card number, as a string without any separators." }, "cvc": { "type": "string", "description": "Card security code." }, "expMonth": { "type": "string", "description": "Two-digit number representing the card's expiration month." }, "expYear": { "type": "string", "description": "Two-digit number representing the card's expiration year." }, "cardholderName": { "$ref": "#/components/schemas/CardholderName" }, "cardholderEmail": { "$ref": "#/components/schemas/CardholderEmail" } } }, "Payment-PaymentMethodBizumInput": { "type": "object", "description": "Details about the Bizum account used for this payment.\nIf provided phone number is valid and registered in Bizum,\nMONEI will try to confirm the payment directly.\n", "properties": { "phoneNumber": { "type": "string", "example": null, "description": "Phone number in E.164 format used to pay with `bizum`." } } }, "Payment-PaymentMethodInput": { "type": "object", "description": "An information about a payment method used for this payment.\nWe recommend using `paymentToken` instead, as it is more secure\nway to pass sensitive payment information. Processing credit\ncard information on your server requires\n[PCI DSS compliance](https://www.investopedia.com/terms/p/pci-compliance.asp).\n", "properties": { "card": { "$ref": "#/components/schemas/Payment-PaymentMethodCardInput" }, "bizum": { "$ref": "#/components/schemas/Payment-PaymentMethodBizumInput" } } }, "Payment-PaymentMethods": { "type": "array", "items": { "type": "string" }, "enum": [ "alipay", "card", "bizum", "paypal", "mbway", "multibanco", "iDeal", "bancontact", "sofort", "trustly", "sepa", "klarna", "giropay", "eps", "blik" ], "x-enumDescriptions": { "alipay": "Alipay", "card": "Card", "bizum": "Bizum", "paypal": "PayPal", "mbway": "MB WAY", "multibanco": "Multibanco", "iDeal": "iDEAL", "bancontact": "Bancontact", "sofort": "SOFORT", "trustly": "Trustly", "sepa": "SEPA", "klarna": "Klarna", "giropay": "Giropay", "eps": "EPS", "blik": "BLIK" }, "example": [ "card", "bizum", "paypal" ], "description": "An array of allowed payment methods (used in hosted payment\npage). Must be enabled payment methods.\n" }, "Payment-TransactionType": { "type": "string", "example": "SALE", "default": "SALE", "enum": [ "SALE", "AUTH", "PAYOUT", "VERIF" ], "x-enumDescriptions": { "SALE": "Automatically captures funds when the customer authorizes the payment", "AUTH": "Places a hold on funds without immediate capture, allowing for later capture", "PAYOUT": "Sends funds to the customer", "VERIF": "Verifies the payment method without placing a hold or capturing funds" }, "description": "Controls when the funds will be captured.\n" }, "Payment-MessageChannel": { "type": "string", "example": "EMAIL", "enum": [ "EMAIL", "WHATSAPP", "SMS" ], "x-enumDescriptions": { "EMAIL": "Send message via email", "WHATSAPP": "Send message via WhatsApp", "SMS": "Send message via SMS text message" }, "description": "The channel used to send the payment message.\n" }, "Payment-MessageLanguage": { "type": "string", "example": "en", "enum": [ "en", "es", "ca", "pt", "de", "it", "fr" ], "x-enumDescriptions": { "en": "English", "es": "Spanish", "ca": "Catalan", "pt": "Portuguese", "de": "German", "it": "Italian", "fr": "French" }, "description": "The language of message sent to the customer. If not provided the default customer language is used if available." }, "Payment-Shop": { "type": "object", "description": "The information about the shop (used in\n[hosted payment page](https://docs.monei.com/integrations/use-prebuilt-payment-page/)).\n", "properties": { "name": { "type": "string", "example": "Test Shop", "description": "The shop name." }, "country": { "$ref": "#/components/schemas/Country" } } }, "Payment-BillingDetails": { "type": "object", "description": "Billing information associated with the payment method\nat the time of the transaction.\n", "properties": { "name": { "type": "string", "example": "John Doe", "description": "The customer's billing full name." }, "email": { "type": "string", "example": "john.doe@example.com", "description": "The customer's billing email address." }, "phone": { "type": "string", "example": null, "description": "The customer's billing phone number in E.164 format." }, "company": { "type": "string", "example": null, "description": "Billing company name." }, "taxId": { "type": "string", "example": null, "description": "Company tax ID." }, "address": { "$ref": "#/components/schemas/Address" } } }, "Payment-ShippingDetails": { "type": "object", "description": "Shipping information associated with the payment.", "properties": { "name": { "type": "string", "example": "John Doe", "description": "The shipping customer's full name." }, "email": { "type": "string", "example": "john.doe@example.com", "description": "The shipping customer's email address." }, "phone": { "type": "string", "example": null, "description": "The shipping customer's phone number in E.164 format." }, "company": { "type": "string", "example": null, "description": "Name of the company where the shipment is going." }, "taxId": { "type": "string", "example": null, "description": "Company tax ID." }, "address": { "$ref": "#/components/schemas/Address" } } }, "Payment-SessionDetails": { "description": "Information related to the browsing session of the user\nwho initiated the payment.\n", "properties": { "ip": { "$ref": "#/components/schemas/IP" }, "countryCode": { "$ref": "#/components/schemas/Country" }, "lang": { "$ref": "#/components/schemas/Lang" }, "deviceType": { "$ref": "#/components/schemas/DeviceType" }, "deviceModel": { "$ref": "#/components/schemas/DeviceModel" }, "browser": { "$ref": "#/components/schemas/Browser" }, "browserVersion": { "$ref": "#/components/schemas/BrowserVersion" }, "os": { "$ref": "#/components/schemas/Os" }, "osVersion": { "$ref": "#/components/schemas/OsVersion" }, "source": { "$ref": "#/components/schemas/Source" }, "sourceVersion": { "$ref": "#/components/schemas/SourceVersion" }, "userAgent": { "$ref": "#/components/schemas/UserAgent" }, "browserAccept": { "$ref": "#/components/schemas/BrowserAccept" }, "browserColorDepth": { "$ref": "#/components/schemas/BrowserColorDepth" }, "browserScreenHeight": { "$ref": "#/components/schemas/BrowserScreenHeight" }, "browserScreenWidth": { "$ref": "#/components/schemas/BrowserScreenWidth" }, "browserTimezoneOffset": { "$ref": "#/components/schemas/BrowserTimezoneOffset" } } }, "Payment-TraceDetails": { "description": "Information related to the browsing session of the user\nwho initiated the payment.\n", "properties": { "ip": { "$ref": "#/components/schemas/IP" }, "countryCode": { "$ref": "#/components/schemas/Country" }, "lang": { "$ref": "#/components/schemas/Lang" }, "deviceType": { "$ref": "#/components/schemas/DeviceType" }, "deviceModel": { "$ref": "#/components/schemas/DeviceModel" }, "browser": { "$ref": "#/components/schemas/Browser" }, "browserVersion": { "$ref": "#/components/schemas/BrowserVersion" }, "os": { "$ref": "#/components/schemas/Os" }, "osVersion": { "$ref": "#/components/schemas/OsVersion" }, "source": { "$ref": "#/components/schemas/Source" }, "sourceVersion": { "$ref": "#/components/schemas/SourceVersion" }, "userAgent": { "$ref": "#/components/schemas/UserAgent" }, "browserAccept": { "$ref": "#/components/schemas/BrowserAccept" }, "browserColorDepth": { "$ref": "#/components/schemas/BrowserColorDepth" }, "browserScreenHeight": { "$ref": "#/components/schemas/BrowserScreenHeight" }, "browserScreenWidth": { "$ref": "#/components/schemas/BrowserScreenWidth" }, "browserTimezoneOffset": { "$ref": "#/components/schemas/BrowserTimezoneOffset" }, "userId": { "type": "string", "example": null, "description": "The ID of the user that started the operation." }, "userEmail": { "type": "string", "example": "user@example.com", "description": "The email of the user that started the operation." } } }, "Payment-NextAction": { "type": "object", "description": "If present, this property tells you what actions you need\nto take in order for your customer to fulfill a payment\nusing the provided source.\n", "properties": { "type": { "type": "string", "example": "CONFIRM", "enum": [ "CONFIRM", "CHALLENGE", "FRICTIONLESS_CHALLENGE", "BIZUM_CHALLENGE", "COMPLETE" ], "description": "- `CONFIRM` - Your customer needs to be redirected to a\n [hosted payment page](https://docs.monei.com/integrations/use-prebuilt-payment-page/)\n or confirm payment using\n [payment token](https://docs.monei.com/integrations/build-custom-checkout/#3-confirm-the-payment-client-side).\n The **redirectUrl** will point to the hosted payment page.\n- `FRICTIONLESS_CHALLENGE` - Your customer needs to be redirected to the frictionless\n 3d secure challenge page provided by the bank. The **redirectUrl**\n will point to the frictionless 3d secure challenge page provided by the bank.\n- `CHALLENGE` - Your customer needs to be redirected to the\n 3d secure challenge page provided by the bank. The **redirectUrl**\n will point to the 3d secure challenge page provided by the bank.\n- `COMPLETE` - The payment is completed. The **redirectUrl** will be\n the **completeUrl** if it was provided when the payment was created.\n- `BIZUM_CHALLENGE` - Your customer will be redirected to the Bizum hosted payment page.\n" }, "mustRedirect": { "type": "boolean", "example": false, "description": "If `true` you have to redirect your customer to the **redirectUrl**\nto continue payment process.\n" }, "redirectUrl": { "type": "string", "example": "https://secure.monei.com/payments/af6029f80f5fc73a8ad2753eea0b1be0", "description": "Redirect your customer to this url to continue payment process.\n" } } }, "Payment-CallbackUrl": { "type": "string", "example": "https://example.com/checkout/callback", "description": "The URL to which a payment result should be sent asynchronously.\n" }, "Payment-CompleteUrl": { "type": "string", "example": "https://example.com/checkout/complete", "description": "The URL the customer will be directed to after transaction\ncompleted (successful or failed - except if `failUrl` is provided).\n" }, "Payment-FailUrl": { "type": "string", "example": "https://example.com/checkout/fail", "description": "The URL the customer will be directed to after transaction has failed,\ninstead of `completeUrl` (used in hosted payment page). This allows\nto provide two different URLs for successful and failed payments.\n" }, "Payment-CancelUrl": { "type": "string", "example": "https://example.com/checkout/cancel", "description": "The URL the customer will be directed to if they decide to cancel\npayment and return to your website (used in hosted payment page).\n" }, "Payment-RefundReason": { "type": "string", "example": null, "enum": [ "duplicated", "fraudulent", "requested_by_customer" ], "description": "The reason for refunding the Payment." }, "Payment-StoreId": { "type": "string", "example": "e5f28150d9e8974c58ab5ec9c4a880f8734dcf05", "description": "A unique identifier of the Store. If specified the payment is attached to this Store.\n" }, "Payment-PointOfSaleId": { "type": "string", "example": "fb269cccfa0cc021f5d0b8eb1421646c696213e1", "description": "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.\n" }, "Payment-SubscriptionId": { "type": "string", "example": "575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa", "description": "A unique identifier of the Subscription. If specified the payment is attached to this Subscription.\n" }, "Payment-AutoRecover": { "type": "boolean", "example": false, "description": "If set to `true`, the new payment will be automatically created when customer visits the payment link of the previously failed payment. Is automatically set to `true` if `completeUrl` is not provided.(set this value to `true` to create \"Pay By Link\" payments)." }, "Payment-ExpireAt": { "type": "number", "format": "int64", "example": 1663581391, "description": "Payment expiration time." }, "CreatePosAuthTokenRequest": { "type": "object", "properties": { "pointOfSaleId": { "$ref": "#/components/schemas/Payment-PointOfSaleId" }, "storeId": { "$ref": "#/components/schemas/Payment-StoreId" } } }, "Subscription": { "title": "Subscription", "type": "object", "required": [ "id", "accountId", "livemode", "amount", "interval", "intervalCount", "status" ], "properties": { "id": { "$ref": "#/components/schemas/Subscription-Id" }, "amount": { "$ref": "#/components/schemas/Payment-Amount" }, "currency": { "$ref": "#/components/schemas/Payment-Currency" }, "allowedPaymentMethods": { "$ref": "#/components/schemas/Subscription-PaymentMethods" }, "description": { "$ref": "#/components/schemas/Subscription-Description" }, "accountId": { "$ref": "#/components/schemas/AccountId" }, "livemode": { "$ref": "#/components/schemas/Livemode" }, "status": { "$ref": "#/components/schemas/Subscription-Status" }, "customer": { "$ref": "#/components/schemas/Payment-Customer" }, "billingDetails": { "$ref": "#/components/schemas/Payment-BillingDetails" }, "shippingDetails": { "$ref": "#/components/schemas/Payment-ShippingDetails" }, "interval": { "$ref": "#/components/schemas/Subscription-Interval" }, "intervalCount": { "$ref": "#/components/schemas/Subscription-IntervalCount" }, "pauseIntervalCount": { "$ref": "#/components/schemas/Subscription-PauseIntervalCount" }, "skipIntervalCount": { "$ref": "#/components/schemas/Subscription-SkipIntervalCount" }, "lastOrderId": { "$ref": "#/components/schemas/Payment-OrderId" }, "lastPayment": { "$ref": "#/components/schemas/Subscription-LastPayment" }, "paymentMethod": { "$ref": "#/components/schemas/Subscription-PaymentMethod" }, "currentPeriodStart": { "$ref": "#/components/schemas/Subscription-CurrentPeriodStart" }, "currentPeriodEnd": { "$ref": "#/components/schemas/Subscription-CurrentPeriodEnd" }, "trialPeriodEnd": { "$ref": "#/components/schemas/Subscription-TrialPeriodEnd" }, "nextPaymentAt": { "$ref": "#/components/schemas/Subscription-NextPaymentAt" }, "retryCount": { "$ref": "#/components/schemas/Subscription-RetryCount" }, "retrySchedule": { "$ref": "#/components/schemas/Subscription-RetrySchedule" }, "cancelAtPeriodEnd": { "$ref": "#/components/schemas/Subscription-CancelAtPeriodEnd" }, "pauseAtPeriodEnd": { "$ref": "#/components/schemas/Subscription-PauseAtPeriodEnd" }, "traceDetails": { "$ref": "#/components/schemas/Payment-TraceDetails" }, "sequenceId": { "$ref": "#/components/schemas/Payment-SequenceId" }, "callbackUrl": { "$ref": "#/components/schemas/Subscription-CallbackUrl" }, "paymentCallbackUrl": { "$ref": "#/components/schemas/Subscription-PaymentCallbackUrl" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "createdAt": { "$ref": "#/components/schemas/CreatedAt" }, "updatedAt": { "$ref": "#/components/schemas/UpdatedAt" } } }, "CreateSubscriptionRequest": { "title": "CreateSubscriptionRequest", "type": "object", "required": [ "amount", "currency", "interval" ], "properties": { "amount": { "$ref": "#/components/schemas/Payment-Amount" }, "currency": { "$ref": "#/components/schemas/Payment-Currency" }, "interval": { "$ref": "#/components/schemas/Subscription-Interval" }, "intervalCount": { "$ref": "#/components/schemas/Subscription-IntervalCount" }, "allowedPaymentMethods": { "$ref": "#/components/schemas/Subscription-PaymentMethods" }, "description": { "$ref": "#/components/schemas/Subscription-Description" }, "customer": { "$ref": "#/components/schemas/Payment-Customer" }, "billingDetails": { "$ref": "#/components/schemas/Payment-BillingDetails" }, "shippingDetails": { "$ref": "#/components/schemas/Payment-ShippingDetails" }, "trialPeriodEnd": { "$ref": "#/components/schemas/Subscription-TrialPeriodEnd" }, "trialPeriodDays": { "$ref": "#/components/schemas/Subscription-TrialPeriodDays" }, "retrySchedule": { "$ref": "#/components/schemas/Subscription-RetrySchedule" }, "callbackUrl": { "$ref": "#/components/schemas/Subscription-CallbackUrl" }, "paymentCallbackUrl": { "$ref": "#/components/schemas/Subscription-PaymentCallbackUrl" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "UpdateSubscriptionRequest": { "title": "UpdateSubscriptionRequest", "type": "object", "required": [ "id" ], "properties": { "amount": { "$ref": "#/components/schemas/Payment-Amount" }, "interval": { "$ref": "#/components/schemas/Subscription-Interval" }, "intervalCount": { "$ref": "#/components/schemas/Subscription-IntervalCount" }, "allowedPaymentMethods": { "$ref": "#/components/schemas/Subscription-PaymentMethods" }, "description": { "$ref": "#/components/schemas/Subscription-Description" }, "customer": { "$ref": "#/components/schemas/Payment-Customer" }, "billingDetails": { "$ref": "#/components/schemas/Payment-BillingDetails" }, "shippingDetails": { "$ref": "#/components/schemas/Payment-ShippingDetails" }, "trialPeriodEnd": { "$ref": "#/components/schemas/Subscription-TrialPeriodEnd" }, "callbackUrl": { "$ref": "#/components/schemas/Subscription-CallbackUrl" }, "paymentCallbackUrl": { "$ref": "#/components/schemas/Subscription-PaymentCallbackUrl" }, "pauseAtPeriodEnd": { "$ref": "#/components/schemas/Subscription-PauseAtPeriodEnd" }, "cancelAtPeriodEnd": { "$ref": "#/components/schemas/Subscription-CancelAtPeriodEnd" }, "pauseIntervalCount": { "$ref": "#/components/schemas/Subscription-PauseIntervalCount" }, "skipIntervalCount": { "$ref": "#/components/schemas/Subscription-SkipIntervalCount" }, "retrySchedule": { "$ref": "#/components/schemas/Subscription-RetrySchedule" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ActivateSubscriptionRequest": { "title": "ActivateSubscriptionRequest", "type": "object", "properties": { "paymentToken": { "allOf": [ { "$ref": "#/components/schemas/Payment-PaymentToken" } ], "description": "A payment token generated by monei.js\n[Components](https://docs.monei.com/monei-js/overview/) or a paymentToken\n[saved after a previous successful payment](https://docs.monei.com/guides/save-payment-method/).\nIn case of the first one, you will also need to send the `sessionId`\nused to generate the token in the first place.\n" }, "sessionId": { "$ref": "#/components/schemas/Payment-SessionId" }, "addAmount": { "allOf": [ { "$ref": "#/components/schemas/Payment-Amount" } ], "description": "The amount to be added to the subscription's initial payment. A positive integer\nrepresenting how much to charge in the smallest currency unit (e.g.,\n100 cents to charge 1.00 USD).\n" }, "allowedPaymentMethods": { "$ref": "#/components/schemas/Subscription-PaymentMethods" }, "sequenceId": { "$ref": "#/components/schemas/Payment-SequenceId" }, "completeUrl": { "$ref": "#/components/schemas/Payment-CompleteUrl" }, "failUrl": { "$ref": "#/components/schemas/Payment-FailUrl" }, "cancelUrl": { "$ref": "#/components/schemas/Payment-CancelUrl" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "CancelSubscriptionRequest": { "title": "CancelSubscriptionRequest", "type": "object", "properties": { "cancelAtPeriodEnd": { "$ref": "#/components/schemas/Subscription-CancelAtPeriodEnd" } } }, "PauseSubscriptionRequest": { "title": "PauseSubscriptionRequest", "type": "object", "properties": { "pauseAtPeriodEnd": { "$ref": "#/components/schemas/Subscription-PauseAtPeriodEnd" }, "pauseIntervalCount": { "$ref": "#/components/schemas/Subscription-PauseIntervalCount" } } }, "SendSubscriptionLinkRequest": { "title": "SendSubscriptionLinkRequest", "type": "object", "properties": { "customerEmail": { "type": "string", "format": "email", "description": "Customer email to send the subscription link to" }, "customerPhone": { "type": "string", "description": "Customer phone number to send the subscription link to" }, "channel": { "type": "string", "enum": [ "EMAIL", "WHATSAPP", "SMS" ], "x-enumDescriptions": { "EMAIL": "Send message via email", "WHATSAPP": "Send message via WhatsApp", "SMS": "Send message via SMS text message" }, "description": "Channel to use for sending the subscription link" }, "language": { "type": "string", "description": "Language to use for the subscription link message" } } }, "SendSubscriptionStatusRequest": { "title": "SendSubscriptionStatusRequest", "type": "object", "properties": { "customerEmail": { "type": "string", "format": "email", "description": "Customer email to send the subscription status to" }, "customerPhone": { "type": "string", "description": "Customer phone number to send the subscription status to" }, "channel": { "type": "string", "enum": [ "EMAIL", "WHATSAPP", "SMS" ], "x-enumDescriptions": { "EMAIL": "Send message via email", "WHATSAPP": "Send message via WhatsApp", "SMS": "Send message via SMS text message" }, "description": "Channel to use for sending the subscription status" }, "language": { "type": "string", "description": "Language to use for the subscription status message" } } }, "Subscription-Id": { "type": "string", "example": "575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa", "description": "Unique identifier for the subscription." }, "Subscription-Description": { "type": "string", "example": "MoonMail Monthly Lite", "description": "An arbitrary string attached to the subscription. Often useful for\ndisplaying to users.\n" }, "Subscription-Status": { "type": "string", "example": "PENDING", "enum": [ "PENDING", "EXPIRED", "TRIALING", "ACTIVE", "PAST_DUE", "PAUSED", "CANCELED" ], "x-enumDescriptions": { "PENDING": "The subscription has been created but is waiting for initial payment or activation", "EXPIRED": "The subscription has reached its end date or maximum number of attempts without successful payment", "TRIALING": "The subscription is in trial period before the first payment is required", "ACTIVE": "The subscription is currently active and payments are being processed normally", "PAST_DUE": "The most recent payment attempt failed but the subscription will retry according to schedule", "PAUSED": "The subscription is temporarily suspended and will resume based on pause settings", "CANCELED": "The subscription has been permanently terminated and will not process further payments" }, "description": "The status of the subscription." }, "Subscription-PaymentMethod": { "type": "object", "description": "Details about the payment method at the time of the transaction.\n", "properties": { "method": { "type": "string", "example": "card", "enum": [ "card", "bizum" ], "x-enumDescriptions": { "card": "Card", "bizum": "Bizum" }, "description": "Subscription method type." }, "card": { "$ref": "#/components/schemas/Payment-PaymentMethodCard" }, "bizum": { "$ref": "#/components/schemas/Payment-PaymentMethodBizum" } } }, "Subscription-PaymentMethodCard": { "type": "object", "description": "Details about the card used as payment method at the time of the transaction.\n", "properties": { "country": { "$ref": "#/components/schemas/Country" }, "brand": { "type": "string", "example": "visa", "enum": [ "visa", "mastercard", "diners", "amex", "jcb", "unionpay", "unknown" ], "x-enumDescriptions": { "visa": "Visa", "mastercard": "Mastercard", "diners": "Diners Club", "amex": "American Express", "jcb": "JCB", "unionpay": "UnionPay", "unknown": "Unknown" }, "description": "Card brand." }, "type": { "type": "string", "example": "credit", "enum": [ "debit", "credit" ], "x-enumDescriptions": { "debit": "Debit", "credit": "Credit" }, "description": "Card type `debit` or `credit`." }, "threeDSecure": { "type": "boolean", "example": false, "description": "Wether this transaction used 3D Secure authentication." }, "threeDSecureVersion": { "type": "string", "example": "2.1.0", "description": "The protocol version of the 3DS challenge." }, "expiration": { "type": "integer", "format": "int64", "example": 2048544000, "description": "Time at which the card will expire.\nMeasured in seconds since the Unix epoch.\n" }, "last4": { "type": "string", "example": "0004", "description": "The last four digits of the card." }, "fingerprint": { "type": "string", "example": "7f2afde1566286c5fb126bb7e79bef549755cce6033dc429013c46d1365ff0e9", "description": "Unique identifier for the card number.\nUsed to detect duplicate payment methods across customers.\nNot present for tokenized cards.\n" } } }, "Subscription-CallbackUrl": { "type": "string", "example": "https://example.com/subscriptions/callback", "description": "The URL will be called each time subscription status changes. You will receive a subscription object in the body of the request.\n" }, "Subscription-PaymentCallbackUrl": { "type": "string", "example": "https://example.com/payments/callback", "description": "The URL will be called each time subscription creates a new payments. You will receive the payment object in the body of the request.\n" }, "Subscription-Interval": { "type": "string", "example": "month", "enum": [ "minute", "hour", "day", "week", "month", "year" ], "x-enumDescriptions": { "minute": "Minutely", "hour": "Hourly", "day": "Daily", "week": "Weekly", "month": "Monthly", "year": "Yearly" }, "description": "Subscription interval. The `minute` and `hour` intervals are only available in test mode." }, "Subscription-IntervalCount": { "type": "integer", "format": "int32", "example": 1, "description": "Number of intervals between subscription payments." }, "Subscription-PauseIntervalCount": { "type": "integer", "format": "int32", "example": 1, "description": "Number of intervals when subscription will be paused before it activates again." }, "Subscription-SkipIntervalCount": { "type": "integer", "format": "int32", "example": 1, "description": "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.\n" }, "Subscription-LastPayment": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Payment-Id" }, "status": { "$ref": "#/components/schemas/Payment-Status" }, "statusCode": { "$ref": "#/components/schemas/Payment-StatusCode" }, "statusMessage": { "$ref": "#/components/schemas/Payment-StatusMessage" } } }, "Subscription-NextPaymentAt": { "type": "integer", "format": "int64", "example": 1636366897, "description": "The date when the next payment will be made." }, "Subscription-CurrentPeriodStart": { "type": "number", "format": "int64", "example": 1636366897, "description": "The start date of the current subscription period. Measured in seconds since the Unix epoch." }, "Subscription-CurrentPeriodEnd": { "type": "number", "format": "int64", "example": 1636366897, "description": "The end date of the current subscription period. Measured in seconds since the Unix epoch." }, "Subscription-TrialPeriodEnd": { "type": "number", "format": "int64", "example": 1636366897, "description": "The end date of the trial period. Measured in seconds since the Unix epoch." }, "Subscription-RetryCount": { "type": "integer", "format": "int32", "example": 1, "description": "Number of retries left for the subscription." }, "Subscription-CancelAtPeriodEnd": { "type": "boolean", "example": false, "description": "If true, the subscription will be canceled at the end of the current period.\n" }, "Subscription-PauseAtPeriodEnd": { "type": "boolean", "example": false, "description": "If true, the subscription will be paused at the end of the current period.\n" }, "Subscription-TrialPeriodDays": { "type": "integer", "format": "int32", "example": 7, "description": "Number of days the trial period lasts." }, "Subscription-RetrySchedule": { "type": "array", "items": { "type": "object", "properties": { "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ], "x-enumDescriptions": { "day": "Daily", "week": "Weekly", "month": "Monthly", "year": "Yearly" }, "example": "day", "description": "The unit of time to wait before the retry attempt." }, "intervalCount": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 31, "example": 3, "description": "The number of intervals to wait before the retry attempt." } }, "required": [ "interval", "intervalCount" ] }, "example": [ { "interval": "day", "intervalCount": 1 }, { "interval": "day", "intervalCount": 3 }, { "interval": "week", "intervalCount": 1 } ], "description": "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.\nIf not specified, the system's default retry schedule will be used.\n" }, "Subscription-PaymentMethods": { "type": "array", "items": { "type": "string" }, "enum": [ "card", "bizum" ], "x-enumDescriptions": { "card": "Card", "bizum": "Bizum" }, "example": [ "card", "bizum" ], "description": "List of payment methods allowed for subscriptions.\n" } }, "parameters": { "CertificateId": { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the certificate.", "schema": { "type": "string", "example": "a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1" } }, "paymentId": { "name": "id", "in": "path", "required": true, "description": "The payment ID", "schema": { "$ref": "#/components/schemas/Payment-Id" } }, "sequenceId": { "name": "sequenceId", "in": "path", "required": true, "description": "The sequence ID", "schema": { "$ref": "#/components/schemas/Payment-SequenceId" } }, "subscriptionId": { "name": "id", "in": "path", "required": true, "description": "The subscription ID", "schema": { "$ref": "#/components/schemas/Subscription-Id" } } }, "examples": { "CreatePaymentBasicRequest": { "value": { "amount": 110, "currency": "EUR", "orderId": "14379133960355", "paymentToken": "7cc38b08ff471ccd313ad62b23b9f362b107560b", "callbackUrl": "https://example.com/checkout/callback", "completeUrl": "https://example.com/checkout/complete" } }, "ConfirmPaymentBasicRequest": { "value": { "paymentToken": "7cc38b08ff471ccd313ad62b23b9f362b107560b" } }, "CapturePaymentFullRequest": { "value": { "amount": 100 } }, "CancelPaymentFullRequest": { "value": { "cancellationReason": "requested_by_customer" } }, "RefundPaymentFullRequest": { "value": { "amount": 50, "refundReason": "requested_by_customer" } }, "RecurringPaymentBasicRequest": { "value": { "orderId": "14379133960366", "callbackUrl": "https://example.com/checkout/callback" } }, "SendPaymentFullRequest": { "value": { "phoneNumber": "+34500000000", "language": "es" } }, "SendPaymentLinkFullRequest": { "value": { "customerEmail": "john.doe@example.com", "language": "es" } }, "SendPaymentReceiptFullRequest": { "value": { "customerEmail": "john.doe@example.com", "language": "es" } }, "CreateSubscriptionBasicRequest": { "value": { "customer": { "name": "John Doe", "email": "john.doe@monei.com" }, "amount": 110, "currency": "EUR", "interval": "month", "intervalCount": 1, "description": "MoonMail Lite Monthly", "callbackUrl": "https://example.com/subscription/callback", "paymentCallbackUrl": "https://example.com/payment/callback" } }, "ActivateSubscriptionBasicRequest": { "value": { "paymentToken": "7cc38b08ff471ccd313ad62b23b9f362b107560b" } }, "CancelSubscriptionBasicRequest": { "value": { "cancelAtPeriodEnd": true } }, "PauseSubscriptionBasicRequest": { "value": { "pauseAtPeriodEnd": true } }, "UpdateSubscriptionBasicRequest": { "value": { "amount": 990 } }, "SendSubscriptionLinkBasicRequest": { "value": { "customerEmail": "john.doe@monei.com", "channel": "EMAIL", "language": "en" } }, "SendSubscriptionStatusBasicRequest": { "value": { "customerEmail": "john.doe@monei.com", "channel": "EMAIL", "language": "en" } } } }, "tags": [ { "name": "Apple Pay Certificate", "description": "Manage Apple Pay certificates for iOS app integration.\n\nTo accept Apple Pay in your iOS app, you need an Apple Pay Payment Processing Certificate.\nThis API provides a complete certificate management workflow:\n\n1. **Create** - Generate a Certificate Signing Request (CSR)\n2. **Upload to Apple** - Use the CSR to create a certificate in Apple Developer Portal\n3. **Activate** - Upload the signed certificate from Apple to enable payment processing\n4. **Manage** - Enable, disable, or delete certificates as needed\n\nThe private key is securely generated and stored by MONEI. You never need to handle private keys directly.\n" }, { "name": "Apple Pay Domain", "description": "The Apple Pay Domain API allows you to register and manage domains for Apple Pay integration.\n\nWith the Apple Pay Domain API, you can:\n\n- Register domains to use with Apple Pay\n- View currently registered domains\n- Ensure your website is properly configured for Apple Pay payments\n\nApple requires domain verification before you can accept Apple Pay payments on your website.\nThis API simplifies the process of registering your domains with Apple Pay and maintaining\nyour domain verification status.\n\n## Domain registration process\n\nTo accept Apple Pay on your website, you must register your domain with Apple. This process:\n\n1. Verifies that you control the domain\n2. Allows Apple Pay buttons to be displayed on your website\n3. Enables secure payment processing through Apple Pay\n\nOnce registered, your domain will be authorized to display Apple Pay payment options to customers.\n" }, { "name": "Bizum", "description": "The Bizum API allows you to integrate with Spain's popular mobile payment system.\n\nWith the Bizum API, you can:\n\n- Validate customer phone numbers for Bizum compatibility\n- Process payments using Bizum as a payment method\n- Pre-authenticate payments (`transactionType: AUTH`) and capture funds later (up to 30 days)\n- Perform full and partial captures on pre-authenticated payments\n- Offer a seamless mobile payment experience for Spanish customers\n\nBizum is a widely used payment method in Spain that allows customers to make payments\nusing their mobile phone number linked to their bank account. This API provides the\nnecessary tools to incorporate Bizum into your payment options.\n\n## Bizum validation\n\nBefore processing a Bizum payment, you can validate if a customer's phone number is\nregistered with Bizum using the validate-phone endpoint.\n" }, { "name": "Payment Methods", "description": "The Payment Methods API allows you to retrieve available payment methods for an account or a specific payment.\nThis information can be used to display appropriate payment options to your customers.\n\nPayment methods vary by country, currency, and merchant configuration. This API helps you dynamically\ndetermine which payment methods are available for a specific transaction or account.\n\nYou can use this API to:\n\n- Get all payment methods available for an account\n- Get payment methods available for a specific payment\n- Display payment options to your customers based on their location and purchase details\n\n## Payment Methods object\n\nSee [PaymentMethods](https://docs.monei.com/docs/apis/rest/schemas/paymentmethods/) for more\ninformation.\n" }, { "name": "Payments", "description": "The Payments API provides a comprehensive platform for processing transactions and managing the complete payment lifecycle.\n\n### Core Payment Operations\n\n- Create and process payments with multiple payment methods\n- Authorize payments and capture funds later\n- Cancel authorized payments to release reserved funds\n- Refund payments partially or in full\n- Generate detailed receipts for completed payments\n\n### Customer Experience Features\n\n- Send payment requests via WhatsApp, SMS, or Bizum\n- Create and distribute payment links through various channels\n- Generate permanent payment tokens for one-click checkout experiences\n- Support recurring billing and subscription payments\n\n### Implementation Best Practices\n\n- Create one payment per order or customer session for clear transaction records\n- Use the unique payment ID for all subsequent operations on a payment\n- Generate permanent payment tokens (with `generatePaymentToken: true`) for returning customers\n- Implement webhook notifications to receive real-time payment status updates\n\n## Payment Status Codes\n\nThe MONEI API returns a `statusCode` attribute in the Payment response to indicate the outcome of your request. This helps you understand whether an operation was successful or why it failed.\n\n### Success Codes\n\nSuccessful transactions return the following codes:\n\n| Code | Message |\n| ---- | ---------------------------------- |\n| E000 | Transaction approved |\n| E001 | Transaction pending processing |\n| E002 | Transaction pending authentication |\n| E003 | Transaction pending authorization |\n| E004 | Transaction expired |\n\n### Error Codes\n\nError codes are grouped by category to help you quickly identify the type of issue:\n\n#### Configuration Errors (E1xx)\n\nThese errors relate to account configuration issues:\n\n| Code | Message |\n| ---- | ------------------------------------------------------------------------------------------------------------ |\n| E101 | Error with payment processor configuration. Check this in your dashboard or contact MONEI for support |\n| E102 | Invalid or inactive MID. Please contact the acquiring entity |\n| E103 | Operation not allowed/configured for this merchant. Please contact the acquiring entity or MONEI for support |\n| E104 | Partial captures are not enabled in your account, please contact MONEI support |\n| E105 | MOTO Payment are not enabled in your account, please contact MONEI support |\n\n#### Authentication and Request Errors (E15x)\n\nThese errors indicate issues with your API request format or authentication:\n\n| Code | Message |\n| ---- | ----------------------------------------------------------------------------- |\n| E150 | Invalid or malformed request. Please check the message format |\n| E151 | Missing or malformed signature/auth |\n| E152 | Error while decrypting request |\n| E153 | Pre-authorization is expired and cannot be canceled or captured |\n| E154 | The payment date cannot be less than the cancellation or capture date |\n| E155 | The cancellation date exceeded the date allowed for pre-authorized operations |\n| E156 | Unauthorized token |\n\n#### Transaction Processing Errors (E2xx)\n\nThese errors occur during payment processing:\n\n| Code | Message |\n| ---- | ----------------------------------------------------------------- |\n| E200 | Transaction failed during payment processing |\n| E201 | Transaction declined by the card-issuing bank |\n| E202 | Transaction declined by the issuing bank |\n| E203 | Payment method not allowed |\n| E204 | Wrong or not allowed currency |\n| E205 | Incorrect reference / transaction does not exist |\n| E206 | Invalid payment method |\n| E207 | Transaction failed: process time exceeded |\n| E208 | Transaction is currently being processed |\n| E209 | Duplicated operation |\n| E210 | Wrong or not allowed payment amount |\n| E211 | Refund declined by processor |\n| E212 | Transaction has already been captured |\n| E213 | Transaction has already been canceled |\n| E214 | The amount to be captured cannot exceed the pre-authorized amount |\n| E215 | The transaction to be captured has not been pre-authorized yet |\n| E216 | The transaction to be canceled has not been pre-authorized yet |\n| E217 | Transaction denied by processor to avoid duplicated operations |\n| E218 | Error during payment request validation |\n| E219 | Refund declined due to exceeded amount |\n| E220 | Transaction has already been fully refunded |\n| E221 | Transaction declined due to insufficient funds |\n| E222 | The user has canceled the payment |\n| E223 | Waiting for the transaction to be completed |\n| E224 | No reason to decline |\n| E225 | Refund not allowed |\n| E226 | Transaction cannot be completed, violation of law |\n| E227 | Stop Payment Order |\n| E228 | Strong Customer Authentication required |\n| E229 | Expired payment method |\n| E230 | Account or card is closed |\n| E231 | Transaction declined. PIN verification not available |\n\n#### 3D Secure Related Errors (E3xx)\n\nThese errors are related to 3D Secure authentication:\n\n| Code | Message |\n| ---- | ---------------------------------------------------- |\n| E300 | Transaction declined due to security restrictions |\n| E301 | 3D Secure authentication failed |\n| E302 | Authentication process timed out. Please try again |\n| E303 | An error occurred during the 3D Secure process |\n| E304 | Invalid or malformed 3D Secure request |\n| E305 | Exemption not allowed |\n| E306 | Exemption error |\n| E307 | Fraud control error |\n| E308 | External MPI received wrong. Please check the data |\n| E309 | External MPI not enabled. Please contact support |\n| E310 | Transaction confirmation rejected by the merchant |\n| E311 | Transaction failed during the authentication process |\n\n#### Fraud Detection Errors (E4xx)\n\nThese errors are related to fraud detection and risk rules:\n\n| Code | Message |\n| ---- | ------------------------------------------------------ |\n| E400 | Transaction declined. Please contact your issuing bank |\n| E401 | Transaction declined. Please contact your issuing bank |\n\n#### Card Related Errors (E5xx)\n\nThese errors are specific to card payments:\n\n| Code | Message |\n| ---- | ------------------------------------------------------------------ |\n| E500 | Transaction declined during card payment process |\n| E501 | Card rejected: invalid card number |\n| E502 | Card rejected: wrong expiration date |\n| E503 | Card rejected: wrong CVC/CVV2 number |\n| E504 | Card number not registered |\n| E505 | Card is expired |\n| E506 | Error during payment authorization. Please try again |\n| E507 | Cardholder has canceled the payment |\n| E508 | Transaction declined: AMEX cards not accepted by payment processor |\n| E509 | Card blocked temporarily or under suspicion of fraud |\n| E510 | Card does not allow pre-authorization operations |\n| E511 | CVC/CVV2 number is required |\n| E512 | Unsupported card type |\n| E513 | Transaction type not allowed for this type of card |\n| E514 | Transaction declined by card issuer |\n| E515 | Implausible card data |\n| E516 | Incorrect PIN |\n| E517 | Transaction not allowed for cardholder |\n| E518 | The amount exceeds the card limit |\n| E519 | Invalid terminal |\n\n#### Digital Wallet Errors (E6xx)\n\nThese errors are related to digital wallet payments:\n\n| Code | Message |\n| ---- | -------------------------------------------------------------- |\n| E600 | Transaction declined during ApplePay/GooglePay payment process |\n| E601 | Incorrect ApplePay or GooglePay configuration |\n\n#### PayPal Related Errors (E62x)\n\nThese errors are specific to PayPal payments:\n\n| Code | Message |\n| ---- | -------------------------------------------------------------------- |\n| E620 | Transaction declined during PayPal payment process |\n| E621 | Transaction declined during PayPal payment process: invalid currency |\n\n#### Bizum Related Errors (E64x-E65x)\n\nThese errors are specific to Bizum payments:\n\n| Code | Message |\n| ---- | -------------------------------------------------------------------------- |\n| E640 | Bizum transaction declined after three authentication attempts |\n| E641 | Bizum transaction declined due to failed authorization |\n| E642 | Bizum transaction declined due to insufficient funds |\n| E643 | Bizum transaction canceled: the user does not want to continue |\n| E644 | Bizum transaction rejected by destination bank |\n| E645 | Bizum transaction rejected by origin bank |\n| E646 | Bizum transaction rejected by processor |\n| E647 | Bizum transaction failed while connecting with processor. Please try again |\n| E648 | Bizum transaction failed, payee is not found |\n| E649 | Bizum transaction failed, payer is not found |\n| E650 | Bizum REST not implemented |\n| E651 | Bizum transaction declined due to failed authentication |\n| E652 | The customer has disabled Bizum, please use another payment method |\n| E653 | The issuer does not support recurring payments with Bizum |\n\n#### Click To Pay Related Errors (E68x)\n\nThese errors are specific to ClickToPay payments:\n\n| Code | Message |\n| ---- | ------------------------------------------------------ |\n| E680 | Transaction declined during ClickToPay payment process |\n| E681 | Incorrect ClickToPay configuration |\n\n#### Cofidis-related Errors (E7xx)\n\nThese errors are specific to Cofidis payments:\n\n| Code | Message |\n| ---- | --------------------------------------------------- |\n| E700 | Transaction declined during Cofidis payment process |\n\n#### System Errors (E9xx)\n\nThese errors indicate system-level issues:\n\n| Code | Message |\n| ---- | ---------------------------------------------- |\n| E999 | Service internal error. Please contact support |\n" }, { "name": "POS Auth Token", "description": "The POS Auth Token API generates authentication tokens for point-of-sale (POS) terminals.\n\nThese tokens enable app-to-app communication where a merchant application generates a POS auth token via API key, then sends it to MONEI Pay to create payments on a POS terminal.\n\nThe generated token is an RS256-signed JWT valid for 24 hours, containing the merchant account context and optional POS terminal and store identifiers.\n" }, { "name": "Subscriptions", "description": "The Subscriptions API provides a powerful solution for managing recurring billing and subscription-based business models.\n\n## Key Features\n\n### Flexible Billing Options\n\n- **Multiple billing intervals**: Daily, weekly, monthly, or yearly billing cycles\n- **Custom intervals**: Configure non-standard periods using intervalCount (e.g., every 3 months)\n- **Trial periods**: Offer free trials before the first billing cycle begins\n- **Variable amounts**: Update subscription amounts for pricing changes or upgrades\n\n### Complete Lifecycle Management\n\n- **Create subscriptions**: Set up recurring billing plans with customizable parameters\n- **Activate subscriptions**: Begin billing cycles with customer payment information\n- **Pause/Resume**: Temporarily halt billing without cancellation\n- **Update subscriptions**: Modify pricing, billing details, or subscription parameters\n- **Cancel subscriptions**: End recurring billing permanently or at period end\n\n### Customer-Friendly Features\n\n- **Automated recurring payments**: No manual action required for subsequent billing\n- **Consistent billing dates**: Predictable billing on the same day of each period\n- **Payment retry mechanism**: Automatic retries for failed payments\n- **Customer control**: Enable customers to manage their own subscriptions\n\n### Integration Benefits\n\n- **Webhook notifications**: Get real-time updates on subscription status changes\n- **Detailed reporting**: Track subscription metrics and performance\n- **Simplified compliance**: Handle recurring billing requirements automatically\n- **Reduced churn**: Automatic billing helps prevent missed payments\n\n## Testing\n\n### Test Mode Limitations\n\n- **Active subscription limit**: In test mode, you can have only three active subscriptions at any time\n- **Automatic cancellation**: All subscriptions are automatically canceled after twelve payments (except when using the 5565 test card)\n\n### Test Mode Intervals\n\n- **Minute and hour intervals**: Only available in test mode for rapid testing of subscription cycles\n\n### Testing Failed Payments\n\nFor testing subscription payment failures, use a test card with the following characteristics:\n\n- **Test card ending in 5565**: Use test card that ending in 5565 (see [Test card numbers](https://docs.monei.com/testing/#test-card-numbers))\n- **Payment behavior**:\n - The first payment for the subscription will be successful\n - All subsequent payments will fail\n - After the first failed payment, the subscription status changes to `Past due`\n - After three consecutive failed payments, the subscription will be automatically cancelled\n" } ], "paths": { "/apple-pay/certificates": { "post": { "operationId": "applePayCertificates_create", "summary": "Create Certificate", "description": "Creates a new Apple Pay certificate by generating a Certificate Signing Request (CSR).\n\nUse this endpoint to start the certificate creation process for accepting Apple Pay in your iOS app.\n\n## Setup workflow\n\n1. **Call this endpoint** to generate a CSR. The response includes the `csr` field in base64 format.\n\n2. **Decode the CSR** and save it as a `.certSigningRequest` file:\n\n ```bash\n echo \"CSR_VALUE\" | base64 -d > apple_pay.certSigningRequest\n ```\n\n3. **Go to [Apple Developer Portal](https://developer.apple.com/account/resources/certificates/list)**:\n - Navigate to Certificates, Identifiers & Profiles\n - Select your Merchant ID under Identifiers\n - In the \"Apple Pay Payment Processing Certificate\" section, click \"Create Certificate\"\n - Upload the `.certSigningRequest` file from step 2\n - Download the signed certificate (`.cer` file)\n\n4. **Convert the certificate to base64**:\n\n ```bash\n base64 -i apple_pay.cer\n ```\n\n5. **Activate the certificate** using the [Activate Certificate](https://docs.monei.com/apis/rest/apple-pay-certificates-activate/) endpoint with the base64 value.\n\n## Important notes\n\n- **CSRs expire after 24 hours.** Complete the certificate creation in Apple Developer Portal within this window, or generate a new CSR.\n- Each CSR can only be used once. If you need a new certificate, create a new CSR.\n- The private key is securely generated and stored by MONEI. You never need to handle private keys directly.\n- You must be enrolled in the [Apple Developer Program](https://developer.apple.com/programs/) to create certificates.\n- The CSR is cleared from the response after the certificate is activated.\n", "security": [ { "APIKey": [] } ], "tags": [ "Apple Pay Certificate" ], "responses": { "200": { "$ref": "#/components/responses/ApplePayCertificateResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.applePayCertificates.create();\n", "label": "NodeJS" }, { "lang": "PHP", "source": "applePayCertificates->create();\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.apple_pay_certificates.create()\n" } ] }, "get": { "operationId": "applePayCertificates_getAll", "summary": "List Certificates", "description": "Retrieves all Apple Pay certificates for your account.\n\nReturns an array of certificate objects, including both active and inactive certificates.\nUse this to view all certificates and their status.\n", "security": [ { "APIKey": [] } ], "tags": [ "Apple Pay Certificate" ], "responses": { "200": { "$ref": "#/components/responses/ApplePayCertificateListResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.applePayCertificates.getAll();\n", "label": "NodeJS" }, { "lang": "PHP", "source": "applePayCertificates->getAll();\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.apple_pay_certificates.get_all()\n" } ] } }, "/apple-pay/certificates/{id}": { "get": { "operationId": "applePayCertificates_get", "summary": "Get Certificate", "description": "Retrieves a specific Apple Pay certificate by its ID.\n\nReturns the certificate object with its current status, CSR (if not yet activated),\nand expiration date (if activated).\n", "security": [ { "APIKey": [] } ], "tags": [ "Apple Pay Certificate" ], "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "responses": { "200": { "$ref": "#/components/responses/ApplePayCertificateResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.applePayCertificates.get('a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1');\n", "label": "NodeJS" }, { "lang": "PHP", "source": "applePayCertificates->get('a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1');\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.apple_pay_certificates.get(\"a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1\")\n" } ] }, "post": { "operationId": "applePayCertificates_update", "summary": "Update Certificate", "description": "Updates an Apple Pay certificate's active status.\n\nUse this endpoint to enable or disable a certificate. Disabling a certificate\nprevents it from being used for payment token decryption while keeping it available\nfor future use.\n", "security": [ { "APIKey": [] } ], "tags": [ "Apple Pay Certificate" ], "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApplePayCertificateRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/ApplePayCertificateResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.applePayCertificates.update('a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1', {\n active: true\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "applePayCertificates->update(\n 'a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1',\n new UpdateApplePayCertificateRequest(\n [\n 'active' => true\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.apple_pay_certificates.update(\n \"a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1\",\n active=True\n)\n" } ] }, "delete": { "operationId": "applePayCertificates_remove", "summary": "Delete Certificate", "description": "Deletes an Apple Pay certificate.\n\nThis permanently removes the certificate and its associated private key.\nThe certificate will no longer be available for payment processing.\n\n**Warning**: This action cannot be undone. If you only want to temporarily disable\na certificate, use the [Update Certificate](https://docs.monei.com/apis/rest/apple-pay-certificates-update/) endpoint instead.\n", "security": [ { "APIKey": [] } ], "tags": [ "Apple Pay Certificate" ], "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "responses": { "200": { "$ref": "#/components/responses/DeleteApplePayCertificateResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.applePayCertificates.remove('a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1');\n", "label": "NodeJS" }, { "lang": "PHP", "source": "applePayCertificates->remove('a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1');\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.apple_pay_certificates.remove(\"a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1\")\n" } ] } }, "/apple-pay/certificates/{id}/activate": { "post": { "operationId": "applePayCertificates_activate", "summary": "Activate Certificate", "description": "Activates an Apple Pay certificate by uploading the signed certificate from Apple.\n\nAfter creating a certificate in the Apple Developer Portal using your CSR, download\nthe signed certificate and upload it here to activate payment processing.\n\n## Activation process\n\n1. Ensure you have downloaded the signed certificate (`.cer` file) from Apple Developer Portal.\n\n2. Convert the certificate to base64:\n\n ```bash\n base64 -i apple_pay.cer\n ```\n\n3. Call this endpoint with the base64-encoded certificate in the `cert` field.\n\n## Validation\n\nThe certificate is validated to ensure:\n\n- It matches the private key generated when creating the CSR\n- It has a valid expiration date\n\nOnce activated, the certificate becomes available for decrypting Apple Pay payment tokens\nin your iOS app.\n\n## Notes\n\n- A certificate can only be activated once.\n- The CSR is cleared after successful activation.\n- The expiration date is extracted and stored for monitoring.\n", "security": [ { "APIKey": [] } ], "tags": [ "Apple Pay Certificate" ], "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateApplePayCertificateRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/ApplePayCertificateResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.applePayCertificates.activate('a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1', {\n cert: 'MIIEpDCCA4ygAwIBAgIIU...'\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "applePayCertificates->activate(\n 'a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1',\n new ActivateApplePayCertificateRequest(\n [\n 'cert' => 'MIIEpDCCA4ygAwIBAgIIU...'\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.apple_pay_certificates.activate(\n \"a6ea0c67-d061-4f7c-9e3b-4a96a6e1e8b1\",\n cert=\"MIIEpDCCA4ygAwIBAgIIU...\"\n)\n" } ] } }, "/apple-pay/domains": { "post": { "operationId": "applePayDomain_register", "summary": "Register Domain", "description": "Registers a domain with Apple Pay.\n\nThis endpoint allows you to register your website domain with Apple Pay, which is required\nbefore you can accept Apple Pay payments on your website. The domain must be accessible\nvia HTTPS and have a valid SSL certificate.\n\nBefore registering, you must download\nthis [domain association file](https://assets.monei.com/apple-pay/apple-developer-merchantid-domain-association/)\nand host it at `/.well-known/apple-developer-merchantid-domain-association` on your site.\n\nFor example, if you're registering `example.com`, make that file available\nat `https://example.com/.well-known/apple-developer-merchantid-domain-association`.\n\nAfter registration, Apple will verify your domain. Once verified, you can display\nApple Pay buttons and process Apple Pay payments on your website.\n", "security": [ { "APIKey": [] } ], "tags": [ "Apple Pay Domain" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterApplePayDomainRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/RegisterApplePayDomainResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.applePayDomain.register({\n domainName: 'example.com'\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "applePayDomain->register(\n new RegisterApplePayDomainRequest(\n [\n 'domain_name' => 'example.com'\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.apple_pay_domain.register(domain_name=\"example.com\")\n" } ] } }, "/bizum/validate-phone": { "post": { "operationId": "bizum_validatePhone", "summary": "Validate Phone", "description": "Validates if a phone number is registered with Bizum.\n\nUse this endpoint to check if a customer's phone number can be used for Bizum payments\nbefore attempting to process a payment. This helps provide a better user experience by\npreventing failed payment attempts for non-registered numbers.\n\nThe response will indicate whether the phone number is valid for Bizum payments.\n", "security": [ { "APIKey": [] } ], "tags": [ "Bizum" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateBizumPhoneRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/ValidateBizumPhoneResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.bizum.validatePhone({\n accountId: '6dccce85-b290-40c2-bb9c-57bc7ecfaf04',\n phoneNumber: '+34600000000'\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "bizum->validatePhone(\n new ValidateBizumPhoneRequest(\n [\n 'account_id' => '6dccce85-b290-40c2-bb9c-57bc7ecfaf04',\n 'phone_number' => '+34600000000'\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.bizum.validate_phone(\n account_id=\"6dccce85-b290-40c2-bb9c-57bc7ecfaf04\", phone_number=\"+34600000000\"\n)\n" } ] } }, "/payment-methods": { "get": { "operationId": "paymentMethods_get", "summary": "Get Payment Methods", "description": "Retrieve available payment methods for an account or a specific payment.\n\nYou can provide either an `accountId` or a `paymentId` as a query parameter to get the available payment methods.\n\nWhen providing a `paymentId`, the response will include additional payment-specific information such as amount and currency.\nThis is useful when you want to show payment options that are specifically available for a particular transaction.\n\nWhen providing an `accountId`, the response will include all payment methods available for that account based on\nthe merchant's configuration and supported payment methods.\n", "tags": [ "Payment Methods" ], "parameters": [ { "name": "accountId", "in": "query", "description": "The ID of the account to get payment methods for", "required": false, "schema": { "type": "string" } }, { "name": "paymentId", "in": "query", "description": "The ID of the payment to get payment methods for", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/GetPaymentMethodsResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.paymentMethods.get({accountId: '6dccce85-b290-40c2-bb9c-57bc7ecfaf04'});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "paymentMethods->get(\n new GetPaymentMethodsRequest(\n [\n 'account_id' => '6dccce85-b290-40c2-bb9c-57bc7ecfaf04'\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\n\n# Get payment methods by accountId\nmonei.payment_methods.get(accountId=\"6dccce85-b290-40c2-bb9c-57bc7ecfaf04\")\n" } ] } }, "/payments": { "post": { "operationId": "payments_create", "summary": "Create Payment", "description": "Creates a new payment with the specified parameters.\n\nYou can create a payment in two ways:\n\n1. **Immediate processing**: Provide a `paymentToken` or `paymentMethod` - The payment will be processed instantly\n2. **Deferred processing**: Create without payment details - The payment remains in `PENDING` status until you\n confirm it later using the [confirm endpoint](https://docs.monei.com/apis/rest/payments-confirm/)\n\nWhen creating a payment without payment details, you can redirect customers to the hosted payment page\nwhere they can select their preferred payment method and complete the transaction.\n\nFor immediate processing, use one of these token options:\n\n- A temporary `paymentToken` generated on the frontend using [monei.js Components](https://docs.monei.com/monei-js/overview/)\n- A permanent `paymentToken` from a previous successful payment (when `generatePaymentToken: true` was included)\n\nPermanent tokens enable one-click checkout experiences for returning customers by allowing you to\nsecurely store and reuse payment details without requiring customers to re-enter their information.\n", "security": [ { "APIKey": [] } ], "tags": [ "Payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" }, "examples": { "basic": { "$ref": "#/components/examples/CreatePaymentBasicRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Payment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.payments.create({\n amount: 110, // 1.10 EUR\n currency: 'EUR',\n orderId: '000001',\n callbackUrl: 'https://example.com/checkout/callback',\n completeUrl: 'https://example.com/checkout/complete'\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "payments->create(\n new CreatePaymentRequest(\n [\n 'amount' => 110, // 1.10 EUR\n 'order_id' => '000001',\n 'currency' => 'EUR',\n 'callback_url' => 'https://example.com/checkout/callback',\n 'complete_url' => 'https://example.com/checkout/complete',\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import CreatePaymentRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.payments.create(\n CreatePaymentRequest(\n amount=110,\n currency=\"EUR\",\n order_id=\"000001\",\n callback_url=\"https://example.com/checkout/callback\",\n complete_url=\"https://example.com/checkout/complete\",\n )\n)\n" } ] } }, "/payments/{id}": { "parameters": [ { "$ref": "#/components/parameters/paymentId" } ], "get": { "operationId": "payments_get", "summary": "Get Payment", "description": "Retrieves the complete details of an existing payment by its unique ID.\n\nThis endpoint returns all available information about the payment, including its current status,\namount, customer details, timestamps, and transaction history. Use this to check the status of\na payment, verify payment details, or retrieve information for your records.\n\nSupply the unique payment ID that was returned from your previous request.\n", "security": [ { "APIKey": [] } ], "tags": [ "Payments" ], "responses": { "200": { "$ref": "#/components/responses/Payment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.payments.get('832b77d1a4b372349a7ae0bb1b2af059');\n", "label": "NodeJS" }, { "lang": "PHP", "source": "payments->get('832b77d1a4b372349a7ae0bb1b2af059');\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.payments.get(\"pay_7cc38b08ff471ccd313ad62b23b9f362\")\n" } ] } }, "/payments/{id}/confirm": { "parameters": [ { "$ref": "#/components/parameters/paymentId" } ], "post": { "operationId": "payments_confirm", "summary": "Confirm Payment", "description": "Confirms a payment that was created without payment details. This endpoint can only be used with\npayments in `PENDING` status.\n\nThe two-step payment flow:\n\n1. **Create**: First, create a payment without payment details (status: `PENDING`)\n2. **Confirm**: Then provide payment details to complete the transaction\n\nWhen confirming a payment, you can use:\n\n- A newly generated `paymentToken` from [monei.js Components](https://docs.monei.com/monei-js/overview/)\n- A permanent `paymentToken` from a previous payment (generated with `generatePaymentToken: true`)\n\nUsing permanent payment tokens enables one-click checkout experiences for returning customers\nwithout requiring them to re-enter their payment information.\n\nYou can provide additional customer information during confirmation, which will override\nany corresponding information originally passed in the payment creation request.\n", "security": [ { "APIKey": [] } ], "tags": [ "Payments" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPaymentRequest" }, "examples": { "full": { "$ref": "#/components/examples/ConfirmPaymentBasicRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Payment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.payments.confirm('832b77d1a4b372349a7ae0bb1b2af059', {\n paymentToken: '7cc38b08ff471ccd313ad62b23b9f362b107560b'\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "payments->confirm(\n '832b77d1a4b372349a7ae0bb1b2af059',\n new ConfirmPaymentRequest(\n [\n 'payment_token' => '7cc38b08ff471ccd313ad62b23b9f362b107560b'\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import ConfirmPaymentRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.payments.confirm(\n \"832b77d1a4b372349a7ae0bb1b2af059\",\n ConfirmPaymentRequest(payment_token=\"7cc38b08ff471ccd313ad62b23b9f362b107560b\"),\n)\n" } ] } }, "/payments/{id}/capture": { "parameters": [ { "$ref": "#/components/parameters/paymentId" } ], "post": { "operationId": "payments_capture", "summary": "Capture Payment", "description": "Captures funds from a previously authorized payment. This endpoint can only be used with payments\nin `AUTHORIZED` status. Both full and partial captures are supported — specify an `amount` less\nthan or equal to the original authorized amount to perform a partial capture.\n\nThis operation completes the two-step authorization flow:\n\n1. **Authorize**: Create a payment with `transactionType: AUTH` to hold or validate funds\n2. **Capture**: Transfer the funds to your account when ready to fulfill the order\n\n**Important**: The capture window depends on the payment method:\n\n- **Card payments**: Authorized payments expire after **7 days**.\n- **Bizum payments**: Authorized payments expire after **30 days**.\n\nAfter expiration, they will be marked as `EXPIRED` and can no longer be captured. Be sure to capture\nfunds within the applicable timeframe or communicate with your customer about a new payment.\n", "security": [ { "APIKey": [] } ], "tags": [ "Payments" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapturePaymentRequest" }, "examples": { "full": { "$ref": "#/components/examples/CapturePaymentFullRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Payment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\n// Capture a payment providing the payment id.\n// Optionally you can specify the amount to capture.\n// If amount is not specified, the total amount of the payment will be captured.\nmonei.payments.capture('832b77d1a4b372349a7ae0bb1b2af059', {\n amount: 100 // 1.00 EUR\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "payments->capture(\n '832b77d1a4b372349a7ae0bb1b2af059',\n new CapturePaymentRequest(\n [\n 'amount' => 100\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import CapturePaymentRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.payments.capture(\n \"832b77d1a4b372349a7ae0bb1b2af059\", CapturePaymentRequest(amount=100)\n)\n" } ] } }, "/payments/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/paymentId" } ], "post": { "operationId": "payments_cancel", "summary": "Cancel Payment", "description": "Releases reserved funds from a previously authorized payment. This endpoint can only\nbe used with payments in `AUTHORIZED` status.\n\nThis operation is part of the two-step authorization flow:\n\n1. **Authorize**: Create a payment with `transactionType: AUTH` to reserve funds\n2. **Cancel**: Release the reserved funds if you decide not to capture the payment\n\nCancellation makes the reserved funds available to the customer again and prevents you from\nbeing able to capture those funds in the future. Once cancelled, an authorization cannot be reactivated.\n", "security": [ { "APIKey": [] } ], "tags": [ "Payments" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPaymentRequest" }, "examples": { "full": { "$ref": "#/components/examples/CancelPaymentFullRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Payment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei, PaymentCancellationReason} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.payments.cancel('832b77d1a4b372349a7ae0bb1b2af059', {\n cancellationReason: PaymentCancellationReason.REQUESTED_BY_CUSTOMER\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "payments->cancel(\n '832b77d1a4b372349a7ae0bb1b2af059',\n new CancelPaymentRequest(\n [\n 'cancellation_reason' => PaymentCancellationReason::REQUESTED_BY_CUSTOMER\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import CancelPaymentRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.payments.cancel(\n \"832b77d1a4b372349a7ae0bb1b2af059\",\n CancelPaymentRequest(cancellation_reason=\"requested_by_customer\"),\n)\n" } ] } }, "/payments/{id}/refund": { "parameters": [ { "$ref": "#/components/parameters/paymentId" } ], "post": { "operationId": "payments_refund", "summary": "Refund Payment", "description": "Returns funds from a completed payment back to the customer's original payment method.\n\n**Refund options:**\n\n- **Full refund**: Return the entire payment amount\n- **Partial refund**: Specify an amount less than the original payment\n- **Multiple partial refunds**: Issue several partial refunds until the total payment amount is reached\n\n**Limitations:**\n\n- You can only refund payments that have been successfully processed\n- A payment can only be refunded up to its original amount\n- Once fully refunded, a payment cannot be refunded again\n- Attempting to refund more than the remaining available amount will result in an error\n", "security": [ { "APIKey": [] } ], "tags": [ "Payments" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundPaymentRequest" }, "examples": { "full": { "$ref": "#/components/examples/RefundPaymentFullRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Payment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei, PaymentRefundReason} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.payments.refund('832b77d1a4b372349a7ae0bb1b2af059', {\n refundReason: PaymentRefundReason.REQUESTED_BY_CUSTOMER\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "payments->refund(\n '832b77d1a4b372349a7ae0bb1b2af059',\n new RefundPaymentRequest(\n [\n 'refund_reason' => PaymentRefundReason::REQUESTED_BY_CUSTOMER\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import RefundPaymentRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.payments.refund(\n \"832b77d1a4b372349a7ae0bb1b2af059\",\n RefundPaymentRequest(refund_reason=\"requested_by_customer\"),\n)\n" } ] } }, "/payments/{sequenceId}/recurring": { "parameters": [ { "$ref": "#/components/parameters/sequenceId" } ], "post": { "operationId": "payments_recurring", "summary": "Recurring Payment", "description": "Creates a subsequent charge using the payment details from a previous transaction.\n\nThis endpoint enables recurring billing and subscription payments by:\n\n- Using the same payment method as the original payment\n- Charging the customer without requiring them to re-enter payment details\n- Supporting variable or fixed amounts (defaults to the original payment amount if not specified)\n\n**Prerequisites:**\n\n1. The initial payment must be created with the `sequence` parameter\n2. The initial payment will return a `sequenceId` in the response\n3. This `sequenceId` must be provided in the URL path when making subsequent recurring charges\n\nIdeal for subscription services, membership renewals, and installment payments.\n\n**Need more advanced subscription management?**\nFor comprehensive subscription management with features like billing cycles, trial periods,\nand automatic recurring billing, consider using the [Subscriptions API](https://docs.monei.com/apis/rest/subscriptions/)\ninstead. It provides a complete solution for creating and managing subscription-based services.\n", "security": [ { "APIKey": [] } ], "tags": [ "Payments" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringPaymentRequest" }, "examples": { "basic": { "$ref": "#/components/examples/RecurringPaymentBasicRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Payment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.payments.recurring('7cc38b08ff471ccd313ad62b23b9f362b107560b', {\n orderId: '000001',\n callbackUrl: 'https://example.com/checkout/callback'\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "payments->recurring(\n '7cc38b08ff471ccd313ad62b23b9f362b107560b',\n new RecurringPaymentRequest(\n [\n 'order_id' => '000001',\n 'callback_url' => 'https://example.com/checkout/callback',\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import RecurringPaymentRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.payments.recurring(\n \"7cc38b08ff471ccd313ad62b23b9f362b107560b\",\n RecurringPaymentRequest(\n order_id=\"000001\",\n callback_url=\"https://example.com/checkout/callback\",\n ),\n)\n" } ] } }, "/payments/{id}/rtp": { "parameters": [ { "$ref": "#/components/parameters/paymentId" } ], "post": { "operationId": "payments_sendRequest", "summary": "Send Payment Request", "description": "Sends a direct payment request to the customer's phone with smart channel selection.\n\n**Smart delivery logic based on customer phone capabilities:**\n\n- If the phone number is registered with Bizum and that payment method is available:\n The customer receives a push notification in their banking app to instantly approve the payment\n- If Bizum is not available or the phone is not registered with Bizum:\n The customer receives a payment link via WhatsApp to complete the payment\n\nThis endpoint provides a streamlined payment experience, especially for Spanish customers\nwith Bizum integration, enabling quick and convenient mobile payments.\n", "security": [ { "APIKey": [] } ], "tags": [ "Payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendPaymentRequestRequest" }, "examples": { "full": { "$ref": "#/components/examples/SendPaymentFullRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Payment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei, PaymentMessageLanguage} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.payments.sendRequest('832b77d1a4b372349a7ae0bb1b2af059', {\n phoneNumber: '+34500000000',\n language: PaymentMessageLanguage.ES\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "payments->sendRequest(\n '832b77d1a4b372349a7ae0bb1b2af059',\n new SendPaymentRequestRequest(\n [\n 'phone_number' => '+34500000000',\n 'language' => PaymentMessageLanguage::ES\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import SendPaymentRequestRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.payments.send_request(\n \"832b77d1a4b372349a7ae0bb1b2af059\",\n SendPaymentRequestRequest(phone_number=\"+34500000000\", language=\"es\"),\n)\n" } ] } }, "/payments/{id}/link": { "parameters": [ { "$ref": "#/components/parameters/paymentId" } ], "post": { "operationId": "payments_sendLink", "summary": "Send Payment Link", "description": "Sends a payment link to the customer through their preferred communication channel.\n\n**This API can only be used for payments with the following status:**\n\n- Pending\n\n**Delivery channels are automatically selected based on available customer information:**\n\n- If customer email is available: Link is sent via email\n- If customer phone is available: Link is sent via WhatsApp\n- If WhatsApp delivery fails: Link is sent via SMS as a fallback\n\nThe payment link allows customers to complete the payment at their convenience using\ntheir preferred payment method on the secure MONEI payment page. If no customer contact information is provided, the system will use the details stored in the payment record.\n", "security": [ { "APIKey": [] } ], "tags": [ "Payments" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendPaymentLinkRequest" }, "examples": { "full": { "$ref": "#/components/examples/SendPaymentLinkFullRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Payment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei, PaymentMessageLanguage} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.payments.sendLink('832b77d1a4b372349a7ae0bb1b2af059', {\n customerEmail: 'john.doe@example.com',\n language: PaymentMessageLanguage.ES\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "payments->sendLink(\n '832b77d1a4b372349a7ae0bb1b2af059',\n new SendPaymentLinkRequest(\n [\n 'customer_email' => 'john.doe@example.com',\n 'language' => PaymentMessageLanguage::ES\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import SendPaymentLinkRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.payments.send_link(\n \"832b77d1a4b372349a7ae0bb1b2af059\",\n SendPaymentLinkRequest(customer_email=\"john.doe@example.com\", language=\"es\"),\n)\n" } ] } }, "/payments/{id}/receipt": { "parameters": [ { "$ref": "#/components/parameters/paymentId" } ], "post": { "operationId": "payments_sendReceipt", "summary": "Send Payment Receipt", "description": "Sends a payment receipt to the customer through their preferred communication channel.\n\n**This API can only be used for payments with the following status:**\n\n- Succeeded\n\n**Delivery channels are automatically selected based on available customer information:**\n\n- If customer email is available: Receipt is sent via email\n- If customer phone is available: Receipt is sent via WhatsApp\n- If WhatsApp delivery fails: Receipt is sent via SMS as a fallback\n\nThe receipt includes payment details such as amount, date, transaction ID, and merchant\ninformation, providing customers with a record of their successful transaction. If no customer contact information is provided, the system will use the details stored in the payment record.\n", "security": [ { "APIKey": [] } ], "tags": [ "Payments" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendPaymentReceiptRequest" }, "examples": { "full": { "$ref": "#/components/examples/SendPaymentReceiptFullRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Payment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei, PaymentMessageLanguage} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.payments.sendReceipt('832b77d1a4b372349a7ae0bb1b2af059', {\n customerEmail: 'john.doe@example.com',\n language: PaymentMessageLanguage.ES\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "payments->sendReceipt(\n '832b77d1a4b372349a7ae0bb1b2af059',\n new SendPaymentReceiptRequest(\n [\n 'customer_email' => 'john.doe@example.com',\n 'language' => PaymentMessageLanguage::ES\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import SendPaymentReceiptRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.payments.send_receipt(\n \"832b77d1a4b372349a7ae0bb1b2af059\",\n SendPaymentReceiptRequest(customer_email=\"john.doe@example.com\", language=\"es\"),\n)\n" } ] } }, "/pos/auth-token": { "post": { "operationId": "posAuthToken_create", "summary": "Create POS Auth Token", "description": "Generates an RS256-signed JWT token for POS terminal authentication.\n\nUse this endpoint to create an auth token that a POS terminal (via MONEI Pay) can use to process payments. This is designed for app-to-app flows where your backend generates the token and passes it to the MONEI Pay app running on a POS device.\n\n`pointOfSaleId` is optional — when provided, it is included in the JWT payload as `pos_id` and `device_id`, allowing you to associate payments with a specific terminal. `storeId` is also optional — included as `store_id` when provided. If `pointOfSaleId` is omitted, the system generates a `device_id` automatically.\n\nThe token is valid for 24 hours.\n", "security": [ { "APIKey": [] } ], "tags": [ "POS Auth Token" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePosAuthTokenRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/CreatePosAuthTokenResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.posAuthToken.create({\n pointOfSaleId: 'a99993f4b76a1d1a1c7af6ae668b906995aedc93',\n storeId: 'b88882e3a65b0c0b0b6ae5bd557a805884bedb82'\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "posAuthToken->create(\n new CreatePosAuthTokenRequest(\n [\n 'point_of_sale_id' => 'a99993f4b76a1d1a1c7af6ae668b906995aedc93',\n 'store_id' => 'b88882e3a65b0c0b0b6ae5bd557a805884bedb82'\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.pos_auth_token.create(point_of_sale_id=\"a99993f4b76a1d1a1c7af6ae668b906995aedc93\", store_id=\"b88882e3a65b0c0b0b6ae5bd557a805884bedb82\")\n" } ] } }, "/subscriptions": { "post": { "operationId": "subscriptions_create", "summary": "Create Subscription", "description": "Creates a new subscription with the specified parameters.\n\n**Subscription Lifecycle**:\n\n1. When first created, the subscription has a `PENDING` status\n2. To initiate billing, you must call the [activate endpoint](https://docs.monei.com/apis/rest/subscriptions-activate/) with payment details\n3. Once activated, the subscription will automatically bill according to the configured interval\n\n**Key Configuration Parameters**:\n\n- **Billing settings**: Amount, currency, interval (daily, weekly, monthly, yearly)\n- **Schedule customization**: Interval count, trial period duration\n- **Allowed payment methods**: An array of strings specifying which payment methods are allowed for this subscription (e.g., `card`, `bizum`)\n- **Customer information**: Contact details, billing and shipping addresses\n- **Communication**: Callback URLs for webhook notifications about subscription events\n\n**Best Practices**:\n\n- Set clear, descriptive names for subscriptions to help with identification\n- Configure appropriate webhook notifications to monitor subscription status changes\n- Consider offering trial periods to increase customer conversion rates\n- Use metadata to store additional information relevant to your business logic\n", "security": [ { "APIKey": [] } ], "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" }, "examples": { "basic": { "$ref": "#/components/examples/CreateSubscriptionBasicRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Subscription" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.subscriptions.create({\n customer: {\n name: 'John Doe',\n email: 'john.doe@monei.com'\n },\n amount: 110,\n currency: 'EUR',\n interval: 'month',\n intervalCount: 1,\n description: 'MoonMail Lite Monthly',\n callbackUrl: 'https://example.com/subscription/callback',\n paymentCallbackUrl: 'https://example.com/payment/callback'\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": " new PaymentCustomer([\n 'name' => 'John Doe',\n 'email' => 'john.doe@monei.com'\n ]),\n 'amount' => 110,\n 'currency' => 'EUR',\n 'interval' => SubscriptionInterval::MONTH,\n 'interval_count' => 1,\n 'description' => 'MoonMail Lite Monthly',\n 'callback_url' => 'https://example.com/subscription/callback',\n 'payment_callback_url' => 'https://example.com/payment/callback'\n]);\n\n$monei->subscriptions->create($request);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import CreateSubscriptionRequest, PaymentCustomer\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.subscriptions.create(\n CreateSubscriptionRequest(\n amount=110,\n currency=\"EUR\",\n interval=\"month\",\n interval_count=1,\n description=\"MoonMail Lite Monthly\",\n customer=PaymentCustomer(name=\"John Doe\", email=\"john.doe@monei.com\"),\n callback_url=\"https://example.com/subscription/callback\",\n payment_callback_url=\"https://example.com/payment/callback\",\n )\n)\n" } ] } }, "/subscriptions/{id}": { "parameters": [ { "$ref": "#/components/parameters/subscriptionId" } ], "get": { "operationId": "subscriptions_get", "summary": "Get Subscription", "description": "Retrieves the complete details of an existing subscription by its unique ID.\n\nThis endpoint returns comprehensive information about the subscription, including:\n\n- Current status and lifecycle details (active, paused, canceled)\n- Billing configuration (amount, currency, interval)\n- Schedule information (current period, next payment date)\n- Customer and payment method details\n- Payment history (including last payment status)\n- Trial period information (if applicable)\n\nUse this endpoint to check subscription status, verify billing details, or retrieve\ninformation needed for customer support inquiries.\n", "security": [ { "APIKey": [] } ], "tags": [ "Subscriptions" ], "responses": { "200": { "$ref": "#/components/responses/Subscription" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.subscriptions.get('575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa');\n", "label": "NodeJS" }, { "lang": "PHP", "source": "subscriptions->get('575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa');\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.subscriptions.get(\"sub_7cc38b08ff471ccd313ad62b23b9f362\")\n" } ] }, "put": { "operationId": "subscriptions_update", "summary": "Update Subscription", "description": "Updates the configuration of an existing subscription.\n\n**Modifiable Parameters**:\n\n- Billing information (amount, description, allowedPaymentMethods)\n- Customer details (contact information, billing/shipping addresses)\n- Subscription settings (cancelAtPeriodEnd, pauseAtPeriodEnd, skipIntervalCount)\n- Metadata (for your internal tracking)\n\n**Update Effects**:\n\n- Amount changes apply to the next billing cycle\n- Customer information updates take effect immediately\n- Setting `cancelAtPeriodEnd` to true will end the subscription after the current period\n- Setting `pauseAtPeriodEnd` to true will pause billing after the current period\n- Setting `skipIntervalCount` skips billing for the specified number of intervals without changing subscription status\n\n**Note**: Some fundamental properties cannot be changed once a subscription is created,\nincluding currency and billing interval. To modify these, you would need to cancel the\nexisting subscription and create a new one.\n", "security": [ { "APIKey": [] } ], "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionRequest" }, "examples": { "basic": { "$ref": "#/components/examples/UpdateSubscriptionBasicRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Subscription" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.subscriptions.update('575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa', {amount: 990});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "subscriptions->update(\n '575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa',\n new UpdateSubscriptionRequest(\n [\n 'amount' => 990\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import UpdateSubscriptionRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.subscriptions.update(\n \"575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa\", UpdateSubscriptionRequest(amount=990)\n)\n" } ] } }, "/subscriptions/{id}/activate": { "parameters": [ { "$ref": "#/components/parameters/subscriptionId" } ], "post": { "operationId": "subscriptions_activate", "summary": "Activate Subscription", "description": "Activates a subscription by attaching a payment method and initiating the billing cycle.\n\n**Activation Process**:\n\n1. This endpoint transitions a `PENDING` subscription to `ACTIVE` status\n2. An initial payment is created to validate the payment method:\n - For regular subscriptions: First billing cycle payment is processed immediately\n - For trial subscriptions: A zero-amount payment is created to verify the payment method\n\n**Payment Method Updates**:\nIf the subscription is already active, this endpoint can be used to update the payment method.\nThe update process creates a zero-amount payment to verify the new payment method works correctly.\n\n**Important Notes**:\n\n- Subscription billing begins immediately upon successful activation (unless in trial period)\n- The payment method provided will be used for all future recurring charges\n- Activation failures (due to invalid payment method) will keep the subscription in `PENDING` status\n- You can specify `allowedPaymentMethods` to restrict which payment methods (e.g., `card`, `bizum`) are accepted for the subscription\n", "security": [ { "APIKey": [] } ], "tags": [ "Subscriptions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateSubscriptionRequest" }, "examples": { "basic": { "$ref": "#/components/examples/ActivateSubscriptionBasicRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Payment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.subscriptions.activate('575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa', {\n paymentToken: '7cc38b08ff471ccd313ad62b23b9f362b107560b'\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "subscriptions->activate(\n '575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa',\n new ActivateSubscriptionRequest(\n [\n 'payment_token' => '7cc38b08ff471ccd313ad62b23b9f362b107560b'\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import ActivateSubscriptionRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.subscriptions.activate(\n \"575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa\",\n ActivateSubscriptionRequest(\n payment_token=\"7cc38b08ff471ccd313ad62b23b9f362b107560b\"\n ),\n)\n" } ] } }, "/subscriptions/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/subscriptionId" } ], "post": { "operationId": "subscriptions_cancel", "summary": "Cancel Subscription", "description": "Cancels an active subscription, permanently stopping the billing cycle.\n\n**Cancellation Effects**:\n\n- The subscription status changes to `CANCELED`\n- No further charges will be processed\n- Access to subscription services typically ends immediately or at period end (depending on your business rules)\n\n**Important Notes**:\n\n- Cancellation is permanent and cannot be undone\n- To restart service, a new subscription must be created\n- Consider using `pauseAtPeriodEnd` or `cancelAtPeriodEnd` for softer transitions\n\nUse this endpoint when a customer wishes to completely terminate their subscription.\n", "security": [ { "APIKey": [] } ], "tags": [ "Subscriptions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSubscriptionRequest" }, "examples": { "basic": { "$ref": "#/components/examples/CancelSubscriptionBasicRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Subscription" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.subscriptions.cancel('575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa', {cancelAtPeriodEnd: true});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "subscriptions->cancel(\n '575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa',\n new CancelSubscriptionRequest(\n [\n 'cancel_at_period_end' => true\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import CancelSubscriptionRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.subscriptions.cancel(\n \"575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa\",\n CancelSubscriptionRequest(cancel_at_period_end=True),\n)\n" } ] } }, "/subscriptions/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/subscriptionId" } ], "post": { "operationId": "subscriptions_pause", "summary": "Pause Subscription", "description": "Pauses an active subscription, temporarily halting the billing cycle.\n\n**Pause Effects**:\n\n- Billing is immediately suspended\n- The subscription status changes to `PAUSED`\n- No charges will be processed while the subscription remains paused\n- The current billing period end date remains unchanged\n\n**Use Cases**:\n\n- Temporary service interruptions\n- Customer vacation or absence periods\n- Account maintenance or dispute resolution\n\nTo resume billing, use the [resume endpoint](https://docs.monei.com/apis/rest/subscriptions-resume/).\n", "security": [ { "APIKey": [] } ], "tags": [ "Subscriptions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PauseSubscriptionRequest" }, "examples": { "basic": { "$ref": "#/components/examples/PauseSubscriptionBasicRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Subscription" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.subscriptions.pause('575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa', {pauseAtPeriodEnd: true});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "subscriptions->pause(\n '575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa',\n new PauseSubscriptionRequest(\n [\n 'pause_at_period_end' => true\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import PauseSubscriptionRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.subscriptions.pause(\n \"575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa\",\n PauseSubscriptionRequest(pause_at_period_end=True),\n)\n" } ] } }, "/subscriptions/{id}/resume": { "parameters": [ { "$ref": "#/components/parameters/subscriptionId" } ], "post": { "operationId": "subscriptions_resume", "summary": "Resume Subscription", "description": "Resumes a previously paused subscription, reactivating the billing cycle.\n\n**Resume Effects**:\n\n- Billing is immediately reactivated\n- The subscription status changes from `PAUSED` to `ACTIVE`\n- The next billing date is recalculated based on the current date\n- Regular charging schedule resumes according to the subscription interval\n\n**Important Notes**:\n\n- No immediate charge is created when resuming (billing continues on next scheduled date)\n- Any pause duration is added to the current billing period, maintaining the expected number of billing cycles\n- If a significant time has passed, verify that the payment method is still valid\n", "security": [ { "APIKey": [] } ], "tags": [ "Subscriptions" ], "responses": { "200": { "$ref": "#/components/responses/Subscription" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.subscriptions.resume('575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa');\n", "label": "NodeJS" }, { "lang": "PHP", "source": "subscriptions->resume('575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa');\n" }, { "lang": "Python", "source": "import Monei\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.subscriptions.resume(\"sub_7cc38b08ff471ccd313ad62b23b9f362\")\n" } ] } }, "/subscriptions/{id}/link": { "parameters": [ { "$ref": "#/components/parameters/subscriptionId" } ], "post": { "operationId": "subscriptions_sendLink", "summary": "Send Subscription Link", "description": "Sends a subscription activation link to the customer through their preferred communication channel.\n\n**This API can only be used for subscriptions with the following status:**\n\n- Pending\n\n**Delivery channels are automatically selected based on available customer information:**\n\n- If customer email is available: Link is sent via email\n- If customer phone is available: Link is sent via WhatsApp\n- If WhatsApp delivery fails: Link is sent via SMS as a fallback\n\nThe subscription activation link allows customers to complete their subscription setup by providing payment details on the secure MONEI payment page. If no customer contact information is provided, the system will use the details stored in the subscription record.\n", "security": [ { "APIKey": [] } ], "tags": [ "Subscriptions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSubscriptionLinkRequest" }, "examples": { "basic": { "$ref": "#/components/examples/SendSubscriptionLinkBasicRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Subscription" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.subscriptions.sendLink('sub_7cc38b08ff471ccd313ad62b23b9f362', {\n email: 'customer@example.com',\n language: 'en'\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "subscriptions->sendLink(\n 'sub_7cc38b08ff471ccd313ad62b23b9f362',\n new SendSubscriptionLinkRequest(\n [\n 'customer_email' => 'customer@example.com',\n 'language' => 'en'\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import SendSubscriptionLinkRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.subscriptions.send_link(\n \"sub_7cc38b08ff471ccd313ad62b23b9f362\",\n SendSubscriptionLinkRequest(customer_email=\"customer@example.com\", language=\"en\"),\n)\n" } ] } }, "/subscriptions/{id}/status": { "parameters": [ { "$ref": "#/components/parameters/subscriptionId" } ], "post": { "operationId": "subscriptions_sendStatus", "summary": "Send Subscription Status", "description": "Sends subscription status information to the customer through their preferred communication channel.\n\n**This API can only be used for subscriptions with the following statuses:**\n\n- Active\n- Trialing\n- Past due\n\n**Delivery channels are automatically selected based on available customer information:**\n\n- If customer email is available: Status is sent via email\n- If customer phone is available: Status is sent via WhatsApp\n- If WhatsApp delivery fails: Status is sent via SMS as a fallback\n\nThe status notification includes subscription details such as current status, upcoming payments, and recent changes. If no customer contact information is provided, the system will use the details stored in the subscription record.\n\n**Email notifications include contextual action links based on subscription status:**\n\n- For past due subscriptions: A link to reactivate the subscription\n- For active and trialing subscriptions: A link to update the payment method\n\nYou can specify the customer's email or phone number, the preferred communication channel (email or SMS), and the language for the message.\n", "security": [ { "APIKey": [] } ], "tags": [ "Subscriptions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSubscriptionStatusRequest" }, "examples": { "basic": { "$ref": "#/components/examples/SendSubscriptionStatusBasicRequest" } } } } }, "responses": { "200": { "$ref": "#/components/responses/Subscription" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import {Monei} from '@monei-js/node-sdk';\n\nconst monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');\n\nmonei.subscriptions.sendStatus('sub_7cc38b08ff471ccd313ad62b23b9f362', {\n email: 'customer@example.com',\n language: 'en'\n});\n", "label": "NodeJS" }, { "lang": "PHP", "source": "subscriptions->sendStatus(\n 'sub_7cc38b08ff471ccd313ad62b23b9f362',\n new SendSubscriptionStatusRequest(\n [\n 'customer_email' => 'customer@example.com',\n 'language' => 'en'\n ]\n )\n);\n" }, { "lang": "Python", "source": "import Monei\nfrom Monei import SendSubscriptionStatusRequest\n\nmonei = Monei.MoneiClient(api_key=\"pk_test_36cf3e8a15eff3f5be983562ea6b13ec\")\n\nmonei.subscriptions.send_status(\n \"sub_7cc38b08ff471ccd313ad62b23b9f362\",\n SendSubscriptionStatusRequest(customer_email=\"customer@example.com\", language=\"en\"),\n)\n" } ] } } } }