# Recurring

Initiate a token-based recurring payment refers to an automatic billing applied to a customer's payment method at predetermined intervals.
This process involves securely storing a token representing the customer's payment details and using it for subsequent transactions without requiring input each time.

Endpoint: POST /v1/recurring
Version: 1.0.0
Security: merchant, signature

## Security:

  - `merchant` (unknown)
    apiKey in header merchant

  - `signature` (unknown)
    apiKey in header signature

## Header parameters:

  - `merchant` (string, required)

  - `signature` (string, required)

## Request fields (application/json):

  - `payment_method` (string, required)
    Payment method name.
    Enum: "paypal-vault"

  - `token` (string, required)
    Secure payment token representing sensitive payment method information.

  - `order_id` (string, required)
    Unique order identifier defined by the merchant, which can be used to find the payment.

  - `amount` (integer, required)
    Order amount in the smallest currency unit supported by the alternative payment method.
For COP, CRC, HUF, LAK, RSD, and TWD, should pass the integer value of the amount with two zeros at the end (for example, XXXX00, which will be transferred as XXXX.00).

  - `currency` (string, required)
    Three-letter ISO-4217 currency code.

  - `order_description` (string, required)
    Brief order description.
It is used in the email receipt sent to the customer.

  - `order_date` (string)
    Date of order creation defined by the merchant.

  - `customer_account_id` (string)
    Unique customer identifier defined by the merchant.

  - `customer_email` (string, required)
    Customer's email address.

  - `customer_date_of_birth` (string)
    Customer's date of birth.

  - `language` (string)
    Customer language settings.
It is used to translate the email receipt to supported languages. If no language is specified, the email receipt defaults to English.

  - `ip_address` (string, required)
    Public IP address of the cardholder, both IPv4 and IPv6 are supported.
Useful for antifraud checks. For recurring payments, use the last session or registration IP.Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) will result in an 'Invalid IP' error.

  - `platform` (string, required)
    Device platform used by the customer at the time of payment.
APP for application, WEB for desktop web, MOB for mobile web.
    Enum: "APP", "WEB", "MOB"

  - `order_metadata` (object)
    Metadata is useful for storing additional, structured information about an order.

  - `fail_url` (string)
    URL for browser redirect after a failed payment.

  - `token` (string, required)
    Token obtained from a previous transaction, used to authorize recurring payments without customer interaction.
This token must be obtained from a previous successful initial transaction with future_usagepayment_typeunscheduled.

  - `amount` (integer, required)
    Order amount in the smallest currency unit supported by the alternative payment method.
For CNY currency, the amount should be in cents (e.g., 8900 = 89.00 CNY).

  - `order_description` (string, required)
    Brief order description.
The field value is displayed in the customer's Alipay transaction history.It is used in the email receipt sent to the customer.

  - `customer_phone` (string, required)
    Customer's phone number.
Should be provided in international format E.164, starting with the plus + sign.

  - `platform` (string, required)
    Client platform used to select the appropriate customer confirmation path during checkout.
APP opens authorization in an app context, MOB continues in mobile web, WEB runs a desktop browser flow.
    Enum: "APP", "WEB", "MOB"

  - `amount` (integer, required)
    Order amount in the smallest currency unit supported by the alternative payment method.

  - `customer_first_name` (string)
    Customer's first name.

  - `customer_last_name` (string)
    Customer's last name.

  - `token` (string, required)
    Mandate token obtained from a previous Klarna transaction, used to authorize recurring payments without customer interaction.
This token must be obtained from a previous successful initial transaction with future_usagepayment_typerecurring.

  - `amount` (integer, required)
    Order amount in the smallest currency unit supported by the alternative payment method.
Must match the billing_amount authorized when the mandate was created.

  - `currency` (string, required)
    Three-letter ISO-4217 currency code.
Must match the currency authorized when the mandate was created. Klarna does not allow cross currency recurring charges.
    Enum: "AUD", "CAD", "CHF", "CZK", "DKK", "EUR", "GBP", "HUF", "MXN", "NOK", "NZD", "PLN", "RON", "SEK", "USD"

  - `order_description` (string, required)
    Order description displayed to the customer.
It is used in the email receipt sent to the customer.

  - `customer_first_name` (string)
    Customer's first name.
Should be provided for physical_goods.

  - `customer_last_name` (string)
    Customer's last name.
Should be provided for physical_goods.

  - `payment_type_data` (object)
    Klarna boost features and session continuity fields.

  - `payment_type_data.klarna_network_session_token` (string)
    Klarna Web SDK session token.
Highly recommended for Klarna boost features like Express Checkout, On-Site Messaging, and Sign in with Klarna. Enables session continuity and pre-filled customer details.

  - `payment_type_data.klarna_network_data` (string)
    Klarna Network Data (KND). Structured JSON pass-through carrying Klarna payment context across the payment lifecycle.
Highly recommended to include supplementary purchase data, for example order line items, as described in How to send Klarna Network Data.

  - `payment_type_data.klarna_originators` (array)
    Array of third-party systems that are responsible for the request (e.g. Shopify, WooCommerce). If the request is sent through multiple systems before reaching the Solidgate, each system can be represented as an originator.

  - `payment_type_data.klarna_originators.name` (string, required)
    The name of the originator.
    Example: SHOPIFY

  - `payment_type_data.klarna_originators.session_reference` (string, required)
    A reference to the session that is being used.

  - `payment_type_data.klarna_originators.module_name` (string)
    The name of the module that is being used.

  - `payment_type_data.klarna_originators.module_version` (string)
    The version of the module that is being used.

  - `ip_address` (string, required)
    Public IP address of the cardholder, both IPv4 and IPv6 are supported.
Useful for antifraud checks. For recurring payments, use the last session or registration IP.Private IPs in ranges 10.0.0.0 to 10.255.255.255, 172.16.0.0 to 172.31.255.255, and 192.168.0.0 to 192.168.255.255 will result in an 'Invalid IP' error.

  - `token` (string, required)
    Token obtained from a previous transaction, used to authorize recurring payments without customer interaction.
This token must be obtained from a previous successful initial transaction with future_usagepayment_type1-click.

  - `amount` (integer, required)
    Order amount in the smallest currency unit supported by the alternative payment method.
For EUR currency, the amount should be in cents (e.g., 1020 = 10.20 EUR).

  - `amount` (integer, required)
    Order amount in the smallest currency unit supported by the alternative payment method.
Possible local taxes, such as IOF-FX in Brazil.

  - `payment_method` (string, required)
    Payment method name.
Pix payments via redirect to the customer’s bank page.
    Enum: "pix"

  - `token` (string, required)
    Mandate or stored credential token from a completed Pix Automático init payment.

  - `token` (string, required)
    Token obtained from a previous transaction, used to authorize follow-up payments without customer interaction.
This token must be obtained from a previous successful initial transaction with future_usagepayment_typerecurring or unscheduled.

  - `order_description` (string, required)
    Brief order description.
The field value is displayed in the customer's WeChat Pay transaction history.It is used in the email receipt sent to the customer.

  - `product_id` (string, required)
    Unique product identifier.
Product used for one-time purchases, such as upsells or single-use services.

  - `product_id` (string, required)
    Unique product identifier.
Product used for one-time purchases, such as upsells or single-use services.Possible local taxes, such as IOF-FX in Brazil or VAT/PAIS in Argentina.

  - `product_id` (string, required)
    Unique product identifier of the subscription.
Possible local taxes, such as IOF-FX in Brazil.

  - `product_id` (string, required)
    Unique product identifier.
Product used for one-time purchases, such as upsells or single-use services.Possible local taxes, such as IOF-FX in Brazil.

  - `platform` (string, required)
    Client platform used to determine how the payer authorization journey is started.
APP starts authorization in an app context, MOB follows a mobile browser path, WEB uses a desktop browser path.
    Enum: "APP", "WEB", "MOB"

  - `order_id` (string, required)
    Unique order identifier, which can be used to find the payment.
For the first payment, the identifier is defined by the merchant.For recurring subscription-based payments, it is generated by the Solidgate subscription service.

  - `product_id` (string, required)
    Unique product identifier.
Product used for recurring purchases, such as services with ongoing access or a subscription-based model.

  - `token` (string, required)
    Token obtained from a previous transaction, used to authorize recurring payments without customer interaction.
This token must be obtained from a previous successful initial transaction with future_usagepayment_typerecurring.

  - `product_id` (string, required)
    Unique product identifier.
Product used for recurring purchases, such as services with ongoing access or a subscription-based model.Possible local taxes, such as IOF-FX in Brazil or VAT/PAIS in Argentina.

  - `product_id` (string, required)
    Product identifier of the subscription.
Possible local taxes, such as IOF-FX in Brazil.

  - `token` (string, required)
    Mandate or stored credential token from a completed Pix Automático subscription init payment.

## Request examples:

  - `PayPal` (unknown)

  - `Alipay` (unknown)

  - `Blik` (unknown)

  - `GCash` (unknown)

  - `Klarna` (unknown)

  - `MB WAY` (unknown)

  - `Mercado Pago` (unknown)

  - `Pix Automático` (unknown)

  - `SmartPix` (unknown)

  - `UPI` (unknown)

  - `WeChat Pay` (unknown)

  - `Product-based payment PayPal` (unknown)

  - `Product-based payment Alipay` (unknown)

  - `Product-based payment Blik` (unknown)

  - `Product-based payment GCash` (unknown)

  - `Product-based payment MB WAY` (unknown)

  - `Product-based payment Mercado Pago` (unknown)

  - `Product-based payment UPI` (unknown)

  - `Product-based recurring Pix Automático` (unknown)

  - `Product-based recurring SmartPix` (unknown)

  - `Product-based payment WeChat Pay` (unknown)

  - `Subscription payment PayPal` (unknown)

  - `Subscription payment Alipay` (unknown)

  - `Subscription payment Blik` (unknown)

  - `Subscription payment GCash` (unknown)

  - `Subscription payment MB WAY` (unknown)

  - `Subscription payment Mercado Pago` (unknown)

  - `Subscription Pix Automático` (unknown)

  - `Subscription SmartPix` (unknown)

  - `Subscription payment UPI` (unknown)

  - `Subscription payment WeChat Pay` (unknown)

## Response 200:

  - `200` (unknown)
    Request received

## Response 200 fields (application/json):

  - `order` (object)
    Details of an order, including identifiers, timestamps, amounts, status, and customer data.

  - `order.method` (string, required)
    Payment method that was used to process the order.

  - `order.id` (string)
    Unique payment identifier.
    Example: pay_01KMG2ABYPF6XS5DMJQ817C429

  - `order.order_id` (string, required)
    Unique order identifier, which can be used to find the payment.
For the first payment, the identifier is defined by the merchant.For recurring subscription-based payments, it is generated by the Solidgate subscription service.

  - `order.subscription_id` (string)
    Unique subscription identifier.

  - `order.token` (string)
    Token associated with a payment method that can be used for the subsequent payments.

  - `order.created_at` (string, required)
    Datetime when the order was created.

  - `order.updated_at` (string, required)
    Datetime when the order was updated.

  - `order.amount` (integer, required)
    Order amount in the smallest currency unit supported by the alternative payment method.

  - `order.currency` (string, required)
    Three-letter ISO-4217 currency code.

  - `order.order_description` (string, required)
    Brief order description.

  - `order.descriptor` (string)
    Identifying text that appears on a customer’s statement.
It includes information about the transaction and helps the customer recognize the charge and provided only for paypal-vault method.
    Example: google.com

  - `order.status` (string, required)
    Status of the requested order.
    Enum: "created", "processing", "settle_pending", "approved", "declined", "refunded"

  - `order.customer_account_id` (string)
    Unique customer identifier defined by the merchant.

  - `order.customer_email` (string, required)
    Customer's email address.

  - `order.ip_address` (string, required)
    Public IP address of the cardholder, both IPv4 and IPv6 are supported.
Required for antifraud checks. For recurring payments, use the last session or registration IP.Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) will result in an 'Invalid IP' error.

  - `order.processing_amount` (integer)
    Amount of the payment in the smallest currency unit as it was processed by the payment service provider.
This amount may differ from the original order amount due to currency conversion or other processing factors.

  - `order.processing_currency` (string)
    Three-letter ISO-4217 currency code of the payment when it was processed by payment service provider.
In some cases, it is different from the original currency.

  - `order.provider_data` (object)
    Additional data from the payment provider.
Parameters in this object are only available for transactions with paypal-vault method.

  - `order.provider_data.billing_address` (object)
    Billing address details.

  - `order.provider_data.billing_address.country` (string)
    ISO 3166-1 alpha-3 country code of the billing address.

  - `order.provider_data.billing_address.state` (string)
    ISO 3166-2 address state code of the billing address.

  - `order.provider_data.billing_address.city` (string)
    City name.

  - `order.provider_data.billing_address.zip` (string)
    Address zip/postal code.

  - `order.provider_data.billing_address.line1` (string)
    First line of the address.

  - `order.provider_data.billing_address.line2` (string)
    Second line of the address.

  - `order.provider_data.shipping_address` (object)
    Address to ship.
If this field is passed by the merchant - the customer cannot change this address.

  - `order.provider_data.shipping_address.country` (string)
    ISO 3166-1 alpha-3 country code of the shipping address.

  - `order.provider_data.shipping_address.state` (string)
    Code of the state where the person, business or institution is located.

  - `order.provider_data.shipping_address.city` (string)
    City or town where the person, business or institution is located.

  - `order.provider_data.shipping_address.zip` (string)
    Address zip/postal code where the person, business or institution is located.

  - `order.provider_data.shipping_address.line1` (string)
    First line of the address.

  - `order.provider_data.shipping_address.line2` (string)
    Second line of the address.

  - `order.provider_data.payer` (object)
    Details of the payer for transactions conducted via APMs.
It provides key information such as the payer's email, first name, and last name, crucial for identifying the payer in the transaction process.

  - `order.provider_data.payer.account_id` (string)
    Payer or their wallet identifier in the payment provider's system.
Used to uniquely identify the payer.

  - `order.provider_data.payer.first_name` (string)
    Payer's first name, used to identify the individual within the transaction.

  - `order.provider_data.payer.last_name` (string)
    Payer's last name, used to verify the payer's identity.

  - `order.provider_data.payer.phone` (string)
    Phone number of the payer.
Used for communication and identification purposes in the transaction.

  - `order.provider_data.payer.email` (string)
    Email address of the payer.
Used for communication and identification purposes in the transaction.

  - `order.provider_data.merchant` (object)
    Information about the merchant involved in the transaction, useful for identifying the specific PayPal account used for the payment.
This object provides identifiers for merchants, essential for accurate tracking and processing of transactions.

  - `order.provider_data.merchant.account_id` (string)
    Unique merchant PayPal account identifier used in the transaction.
Identifier is critical for associating the transaction with the correct merchant's PayPal account, enabling accurate processing and order reporting.

  - `transactions` (array)
    Details of a transaction, including identifiers, timestamps, amounts, currency, operation type, status, and other relevant data.

  - `transactions.method` (string, required)
    Payment method that was used to process the transaction.

  - `transactions.id` (string)
    Unique identifier associated with a transaction.

  - `transactions.created_at` (string, required)
    Datetime when the transaction was created.

  - `transactions.amount` (integer, required)
    Transaction amount in the smallest currency unit supported by the alternative payment method.

  - `transactions.currency` (string, required)
    Three-letter ISO-4217 currency code.

  - `transactions.status` (string, required)
    Status of the transaction.
    Enum: "created", "processing", "settle_pending", "success", "fail"

  - `transactions.type` (string, required)
    Type of the transaction.
    Enum: "pay", "recurring", "refund"

  - `transactions.refund_reason` (string)
    Text description of the refund reason.

  - `transactions.refund_reason_code` (string)
    Refund reason code.
This field is actively validated against the current list of reason codes. Deprecated codes will not be accepted.

  - `transactions.payer_details` (object)
    Details of the payer for transactions conducted through APMs.
It provides essential information such as the payer's email and the invoice identifier, both of which are specifically applicable to transactions conducted with the PayPal method.

  - `transactions.payer_details.invoice_id` (string)
    Unique invoice identifier provided by PayPal.
    Example: 123443334

  - `transactions.payer_details.payer_email` (string)
    Payer's email.
Should be provided only for the transactions with paypal-vault method.

  - `pay_form` (object)
    Payment form data.
Including fields necessary for processing the payment.

  - `pay_form.return_url` (string)
    URL for browser redirect after a payment process.

  - `pay_form.script_url` (string)
    URL of the JavaScript file required to render the APM payment form during integration, initialization, and configuration.

  - `pay_form.token` (string)
    Secure payment token representing sensitive payment method information.
Token received on the first payment, which should be used for subsequent payments.

  - `payment_type_data` (any)
    Additional data required to make payments with the specific alternative payment methods.
This object is specifically for Boleto, Pix QR, and Pix Automático initial mandate responses with QR payload and expiry.

  - `payment_type_data.amount` (number)
    Amount in the smallest currency unit supported by the alternative payment method.
Should be provided in the currency of the transaction.

  - `payment_type_data.currency` (string)
    Three-letter ISO-4217 currency code.

  - `payment_type_data.expiration_date` (string)
    Expiration date.

  - `payment_type_data.image_url` (string)
    URL of the image representing the full boleto method details.
This provides a visual reference for the user.

  - `payment_type_data.number` (string)
    Ticket number.
Long number customers enter in their bank app or website to complete the payment.

  - `payment_type_data.type` (string)
    Payment method type.
This specifies the category of the alternative payment method being used.

  - `payment_type_data.qr_code_value` (string)
    EMV payload for the customer to scan or copy into a Pix app.

  - `payment_type_data.qr_code_expiration_date` (string)
    Expiration datetime of the QR code.

  - `payment_type_data.qr_code_expiration_date` (string)
    Expiration datetime of the QR code, usually within one hour after issuance.

  - `order_metadata` (object)
    Metadata is useful for storing additional, structured information about an object.

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Unauthorized access due to invalid credentials.
    Example: 1.01

  - `error.messages` (array, required)
    Array of error messages applied to the decline payment.

## Response 200 examples:

  - `Success` (unknown)

  - `Authentication failed` (unknown)

  - `Error 2.01 Invalid data` (unknown)

  - `Error 2.01 Order not found` (unknown)

  - `Error X.XX` (unknown)