# 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: MerchantID

## Header parameters:

  - `merchant` (string, required)
    Unique public key provided upon registration and must be shared for identification purposes.
    Example: "api_pk_7b197...ba108f842"

  - `signature` (string, required)
    Request signature that allows verification of merchant authenticity on the payment gateway server.
    Example: "M2E3OTkyNzcz...xMmExODI4"

## Response 200 fields (application/json):

  - `body` (object) — one of:
    - Success:
      - `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.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.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.
      - `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.
      - `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.


  Should be provided only for the transactions with paypal-vault method.
      - `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 needed to display the PayPal button is required for integration, initialization, configuration.
      - `pay_form.token` (string)
        Secure payment token representing sensitive payment method information.
      - `payment_type_data` (any) — one of:
        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.
        - Boleto:
          - `amount` (number)
            Amount in the smallest currency unit supported by the alternative payment method.


  Should be provided in the currency of the transaction.
          - `currency` (string)
            Three-letter ISO-4217 currency code.
          - `expiration_date` (string)
            Expiration date.
          - `image_url` (string)
            URL of the image representing the full boleto method details.


  This provides a visual reference for the user.
          - `number` (string)
            Ticket number.


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


  This specifies the category of the alternative payment method being used.
        - Pix QR:
          - `qr_code_value` (string)
            Value used to render a QR code or for customers to copy and paste into a Pix app.
          - `qr_code_expiration_date` (string)
            Expiration date of the QR code.
        - Pix Automático:
          - `qr_code_value` (string)
            EMV payload for the customer to scan or copy into a Pix app.
          - `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.
    - Authentication failed:
      - `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.
        Example: ["Authentication failed"]
    - Error:
      - `error` (object, required) — one of (discriminator: code):
        Error object.
        - 2.01 Invalid data:
          - `messages` (array, required)
            Array containing messages that specify why the payment was declined due to validation errors.


  These messages can range from an incorrect card number to an invalid security code or billing address.
            Example: ["Invalid data"]
        - 2.01 Order not found:
          - `messages` (object, required)
            Object containing key-value pairs that clarify the reason for the payment decline, particularly in cases where the requested order does not exist.
        - 2.04 Card brand is not supported:
          - `messages` (array, required)
            Array containing messages that specify why the payment was declined due to unsupported card brand for incremental authorization.


  Supported card brands include American Express (Amex), Cartes Bancaires, Diners, Discover, JCB, Mastercard, Mexico Domestic (Network MX) and Visa.
            Example: ["Card brand is not supported"]
        - X.XX:
          - `messages` (array, required)
            Array containing either strings or objects that provide details about the error or status.


  When it is an array of strings, each string describes a separate issue. When it is an object, the object will contain key-value pairs explaining the issue in more detail.
          - `recommended_message_for_user` (string)
            Message with recommended next steps or additional information.
            Example: "The user’s card balance has insufficient funds."
      - `error.code` (string)
        Gateway error code for the declined payment.