Skip to main content

API de Suscripciones

Ver en POSTMAN

Recurso para obtener las suscripciones dadas de alta en Increase Pay o dar de Alta nuevas suscripciones

Cómo probar​

Recuerda usar la Base URL de Sandbox para hacer pruebas: https://gateway.increase.app/pay-sandbox/public/v1/

URL Producción: https://gateway.increase.app/pay/public/v1/

Recordar siempre enviar en los headers Content-Type: application/json

Crear una suscripción​

POST https://gateway.increase.app/pay/public/v1/subscriptions

ParámetroTipoDescripciónRequerido
customer_idStringId del cliente asociado.si
plan_idStringId del plan de la suscripciónsi
external_idStringIdentificador del cliente en tu sistema.no
tagsString[]Array de strings para agrupar suscripcionesno
payment_method_idStringId del método de pago del clienteno
amountStringMonto de la suscripción (solo necesaria en variable)no
quantityNumberSolo aplica para planes Escalonados, Escalonados base y por Volumenno
trial_period_daysStringDías de prueba gratuitosno
discountsArrayDescuentos asociadosno
one_time_costsArrayPagos únicos asociados.no
taxesArrayImpuestos asociadosno
additional_costsArrayCostos adicionales asociadosno
start_dateStringFecha de inicio de la suscripciónno
end_dateStringFecha de fin de la suscripciónno
process_syncBooleanOpción de pagar en el momentono

En caso de enviar el payment_method_id en vacio la suscripción otorgará luego de crearse un "checkout_link" desde donde el usuario final podrá cargar el medio de pago.

Ejemplo​

{
  "customer_id": "00000000-0000-0000-0000-000000000001",
  "plan_id": "00000000-0000-0000-0000-000000000002",
  "payment_method_id": "00000000-0000-0000-0000-000000000002",
  "start_date": "2020-04-17",
  "end_date": "2020-04-30",
  "quantity": 1,
  "trial_period_days": 7,
  "discounts": [
    {
      "id": "00000000-0000-0000-0000-000000000001"
    }
  ],
  "one_time_costs": [
    {
      "id": "00000000-0000-0000-0000-000000000001"
    }
  ],
  "taxes": [
    {
      "id": "00000000-0000-0000-0000-000000000001"
    }
  ],
  "additional_costs": [
    {
      "id": "00000000-0000-0000-0000-000000000001"
    }
  ]
}

Cobrar en el momento.​

Reglas de facturacion en el momento de la creacion:​

  1. El plan de la susbripcion debe tener el parametro automatic_subscription_request_approval = true

  2. La suscripción debe ser creada con un payment_method vinculado.

  3. El payment_method debe ser una tarjeta de crédito / débito

  4. La suscripción no debe tener periodo de prueba.

  5. La suscripción no debe programarse para cobrar un día mayor a hoy.

  6. La suscripción debe empezar el mismo dia que es creada ("cobro al inicio del período").

Reglas de activación de una suscripción creadas desde esta nueva funcionalidad:​

  • Si el payment_method especificado es del tipo CBU la suscripción se creara en estado active.
  • Si la suscripción tiene periodo de prueba se creara en estado active y se cobrará cuando corresponda al finalizar el período de prueba.
  • Si el payment_method es una tarjeta de credito, y se intenta facturar la suscripcion entonces el estado dependera del resultado del payment.
    • Si el payment falla entonces la suscripcion quedará en estado pending.
    • Si el payment es exitoso entonces la suscripcion quedará en estado active.

Cómo probar​

POST https://gateway.increase.app/pay/public/v1/subscriptions

⚠️ El parametro process_sync es opcional y si se lo setea en true se utilizara el flujo de pago en el momento y se aplicaran las reglas antes descritas.

Ejemplo​

{
  "process_sync": true,
  "quantity": 1,
  "trial_period_days": 0,
  "amount": 100,
  "end_date": null,
  "external_id": "AA11110000",
  "plan_id": "b1eda8d4-e0ce-4411-bf33-8e4ad55c16b6",
  "customer_id": "f58fabcd-7635-4cc0-adf1-19f1f3ea5abd",
  "payment_method_id": "855784a6-bd1b-4f4f-9fbe-f78fdc30a56b"
}

Obtener todas las suscripciones​

GET https://gateway.increase.app/pay/public/v1/subscriptions

Parámetros optativos​

ParámetroTipoDescripción
pageIntegerIndica la página a obtener resultados.
per_pageIntegerCantidad de resultados por página (Máximo 40).
customer_idStringId del cliente asociado.
plan_idStringId del plan de la suscripción
product_idStringId del producto.
external_idStringIdentificador del cliente en tu sistema.
tagsString[]Array de strings que deben cumplir los tags de las suscripciones.
created_at_fromStringFecha + Hora en formato ISO 8601. Ej: 2020-10-10T00:00:00
created_at_toStringFecha + Hora en formato ISO 8601. Ej: 2020-10-10T00:00:00
paused_at_fromStringFecha + Hora en formato ISO 8601. Ej: 2020-10-10T00:00:00
paused_at_toStringFecha + Hora en formato ISO 8601. Ej: 2020-10-10T00:00:00
canceled_at_fromStringFecha + Hora en formato ISO 8601. Ej: 2020-10-10T00:00:00
canceled_at_toStringFecha + Hora en formato ISO 8601. Ej: 2020-10-10T00:00:00
statusStringValores posibles: active pending scheduled paused canceled finished trial grace_period pending_approval request_rejected pending_payment pending_canceled pending_finished

Ejemplo

`https://gateway.increase.app/pay/public/v1/subscriptions?page=1&per_page=20&status=active&customer_id=00000000-0000-0000-0000-000000000001&poduct_id=00000000-0000-0000-0000-000000000001`

Obtener una suscripción​

GET https://gateway.increase.app/pay/public/v1/subscriptions/<id>

Response

{
  "id": "b6fe4476-bff5-4fc9-8e93-164ad89c241e",
  "plan": {
      "id": "23b8b75f-0679-46ca-9ffb-5377f530b01a",
      "name": "New plan cbu",
      "amount": "2500.0",
      "currency": "ARS",
      "cycle_unit": "monthly",
      "cycle_amount": 1,
      "type": "flat",
      "country": "ARG",
      "external_id": "41b24ea0-8cf5-48fa-a206-05db619a5231",
      "trial_period_days": 10,
      "tiers": [],
      "charge_after_period": false,
      "product_id": "8e0bda25-c446-48a9-aab0-a9a7adc396fd",
      "start_day": null,
      "charge_proportional": null,
      "automatic_subscription_request_approval": true,
      "checkout_link": "https://gateway.increase.app/pay-sandbox/checkout/v1/short_urls/oP23wN",
      "success_url": "",
      "collect_methods": {
          "cbu": [
              {
                  "id": "a2bb722a-9d6d-4bdc-92ec-a8e329ec7358",
                  "name": "comafi",
                  "type": "comafi",
                  "status": "enabled",
                  "country": "ARG",
                  "max_payment_retries": 1,
                  "retry_period_time": 1,
                  "retry_period_unit": "hours",
                  "currencies": [
                      "ARS"
                  ],
                  "payment_categories": [
                      "cbu"
                  ],
                  "metadata": {
                      "company_code": "merch",
                      "cuit": "30710123388",
                      "account_number": "221312344565671",
                      "beneficiary": "merchantex",
                      "id_size": 1
                  }
              }
          ],
          "card": [],
          "ticket": []
      },
      "locked": false,
      "taxes": [
          {
              "id": "9cacf4ba-080f-4120-a84e-6b824e92fe39",
              "type": "flat",
              "name": "New tax",
              "amount": "130.0",
              "region": null,
              "created_at": "2021-09-30T15:04:36-03:00",
              "country": "ARG",
              "description": "Tax description updated",
              "external_id": "9e8bc664-dd8f-4477-8336-0d2663536c86"
          }
      ],
      "discounts": [
          {
              "id": "bd9a61bd-c7f1-4920-a832-a43a5084b6f1",
              "external_id": "e2dfa853-aba1-4512-846c-c10e42143135",
              "name": "New discount",
              "type": "flat",
              "amount": "130.0",
              "currency": "ARS",
              "duration": "periodic",
              "cycle_unit": "monthly",
              "cycle_amount": 10,
              "created_at": "2021-09-30T14:54:56-03:00",
              "description": "A description of the discount"
          }
      ],
      "one_time_costs": [
          {
              "id": "716d64f8-1b2f-4bf7-b2ba-3da72382244a",
              "external_id": "994702d6-63b1-43ad-acd0-53686675bf65",
              "type": "flat",
              "name": "New one time cost",
              "description": "A description of the one time cost",
              "amount": "1300.0",
              "country": "ARG",
              "currency": "ARS"
          }
      ]
      "additional_costs": [
        {
          "id": "9d59430f-d37e-4c0d-a1c6-60a771b9324f",
          "external_id": "85c8ed60-20b1-4f31-a513-1a1edd086e0e",
          "name": "30% Paquete premium Prueba",
          "type": "percentage",
          "amount": "0.3",
          "currency": "ARG",
          "duration": "periodic",
          "cycle_unit": "monthly",
          "cycle_amount": 6,
          "created_at": "2023-07-06T18:20:59Z",
          "description": ""
        }
      ],
  },
  "customer": {
      "id": "4b214574-8870-49a0-a91e-3e9ac73fd333",
      "external_id": "",
      "email": "test@test.com",
      "language": "ES",
      "timezone": "Buenos Aires",
      "first_name": "Customer",
      "last_name": "Test",
      "billing_info": {
          "id": "55fcce19-0b77-4c96-ac1c-fff100d86ac2",
          "address_line_1": "Broadway 123",
          "address_line_2": "",
          "country": "ARG",
          "currency": "ARS",
          "city": "City",
          "state": "Buenos Aires",
          "zip_code": "1112",
          "phone": "111212123"
      },
      "tax_id": "20123123458",
      "checkout_link": "https://gateway.increase.app/pay-sandbox/checkout/v1/short_urls/n0EGp2",
      "created_at": "2021-09-29T17:41:12-03:00"
  },
  "quantity": 1,
  "amount": "2500.0",
  "net_amount": "5300.0",
  "currency": "ARS",
  "status": "active",
  "canceled_at": null,
  "paused_at": null,
  "trial_period_end": "2021-10-05T00:00:00-03:00",
  "next_billing_date": "2021-10-05T00:00:00-03:00",
  "created_at": "2021-09-30T16:43:51-03:00",
  "payment_method": {
      "id": "ec266d72-9af8-4fff-b95b-783a7751f0db",
      "external_id": "a2bb722a-9d6d",
      "data": {
          "type": "cbu",
          "country": "ARG",
          "number": "94256727**4643"
      },
      "created_at": "2021-09-30T09:52:24-03:00",
      "collect_method_id": "a2bb722a-9d6d-4bdc-92ec-a8e329ec7358"
  },
  "product": {
      "id": "8e0bda25-c446-48a9-aab0-a9a7adc396fd",
      "name": "New product",
      "external_id": null,
      "created_at": "2021-09-29T15:58:51-03:00",
      "checkout_link": "https://gateway.increase.app/pay-sandbox/checkout/v1/short_urls/qSR6_P"
  },
  "external_id": "edff0eed-67b7-409d-abf2-517ebd0f80a0",
  "activate_at": "2021-09-30",
  "cancel_at": null,
  "checkout_link": "https://gateway.increase.app/pay-sandbox/checkout/v1/short_urls/WUGFi3",
  "discounts": [
      {
          "id": "bd9a61bd-c7f1-4920-a832-a43a5084b6f1",
          "external_id": "e2dfa853-aba1-4512-846c-c10e42143135",
          "name": "New discount",
          "type": "flat",
          "amount": "130.0",
          "currency": "ARS",
          "duration": "periodic",
          "cycle_unit": "monthly",
          "cycle_amount": 10,
          "cycle_amounts_left": 7,
          "created_at": "2021-09-30T14:54:56-03:00",
          "description": "A description of the discount"
      },
      {
          "id": "bb913fef-135c-4901-a637-c2efb4b37b07",
          "external_id": "e2dfa853-aba1-4512-846c-c10e42143134",
          "name": "New discount for subscription",
          "type": "flat",
          "amount": "120.0",
          "currency": "ARS",
          "duration": "periodic",
          "cycle_unit": "monthly",
          "cycle_amount": 10,
          "cycle_amounts_left": 6,
          "created_at": "2021-09-30T16:42:47-03:00",
          "description": "A description of the discount"
      }
  ],
  "invoices": [],
  "one_time_costs": [
      {
          "id": "716d64f8-1b2f-4bf7-b2ba-3da72382244a",
          "external_id": "994702d6-63b1-43ad-acd0-53686675bf65",
          "type": "flat",
          "name": "New one time cost",
          "description": "A description of the one time cost",
          "amount": "1300.0",
          "country": "ARG",
          "currency": "ARS",
          "cycle_amounts_left": 1,
      },
      {
          "id": "af2fa75f-2bfc-489d-8501-286ae421c7a5",
          "external_id": "asad123-123asd",
          "type": "flat",
          "name": "New one time cost for subscription",
          "description": "A description of the one time cost",
          "amount": "1500.0",
          "country": "ARG",
          "currency": "ARS",
          "cycle_amounts_left": 0,
      }
  ],
  "taxes": [
      {
          "id": "9cacf4ba-080f-4120-a84e-6b824e92fe39",
          "type": "flat",
          "name": "New tax",
          "amount": "130.0",
          "region": null,
          "created_at": "2021-09-30T15:04:36-03:00",
          "country": "ARG",
          "description": "Tax description updated",
          "external_id": "9e8bc664-dd8f-4477-8336-0d2663536c86"
      },
      {
          "id": "e9cc9167-7796-4e10-8ee5-ad6ae4a0beb4",
          "type": "flat",
          "name": "New tax for subscription",
          "amount": "120.0",
          "region": null,
          "created_at": "2021-09-30T16:43:29-03:00",
          "country": "ARG",
          "description": "Tax description",
          "external_id": "9e8bc664-dd8f-4477-8336-0d2663536c85"
      }
  ]
}

Pausar una suscripción​

POST https://gateway.increase.app/pay/public/v1/subscriptions/<id>/pause

Parámetros optativos​

ParámetroTipoDescripción
periodsIntegerCantidad de periodos a pausar la suscripción. Si no se envía, se pausa indefinidamente

Cancelar una suscripción​

PATCH https://gateway.increase.app/pay/public/v1/subscriptions/<id>/cancel

Reactivar una suscripción​

POST https://gateway.increase.app/pay/public/v1/subscriptions/<id>/activate

ParámetroTipoDescripción
start_dateStringFecha de inicio de la suscripción

Actualizar una suscripción específica​

PUT https://gateway.increase.app/pay/public/v1/subscriptions/<id>

ParámetroTipoDescripciónRequerido
next_billing_dateDateFecha del siguiente cobro. Fecha en formato ISO 8601. Ej: 2020-10-10no
trial_period_endDateFecha de finalización del período de prueba. Fecha en formato ISO 8601. Ej: 2020-10-10no
one_time_costsArrayPagos únicos asociados.no
discountsArrayDescuentos asociadosno
taxesArrayImpuestos asociadosno
additional_costsArrayCostos adicionales asociadosno
tagsstring[]Array de strings para agrupar suscripcionesno

Validaciones del next_billing_date​

El next_billing_date se puede cambiar si la suscripción se encuentra en alguno de los siguientes estados:

  • active
  • scheduled
  • trial
  • grace_period

El next billing date tiene un rango valido segun el tipo de subscripcion, la nueva fecha de cobro debe estar dentro del rango permitido:

  • Para suscripciones anuales: +/- 30 días.
  • Para suscripciones mensuales: +/- 5 días.
  • Para suscripciones semanales: +/- 3 días.
  • Para suscripciones personalizadas (diario): ilimitado.

Los dias de limites se pueden interpretar como minimo y maximo es decir

// Para una subscripcion semanal
// siendo 10 de abril del 2022 la fecha de subscription.next_billing_date
// el minimo va a ser 7 de abril del 2022
// el maximo va a ser 13 de abril del 2022

[Thu, 07 Apr 2022, Fri, 08 Apr 2022, Sat, 09 Apr 2022, Sun, 10 Apr 2022, Mon, 11 Apr 2022, Tue, 12 Apr 2022, Wed, 13 Apr 2022]

Ejemplo​

{
  "amount": "200",
  "quantity": 2,
  "trial_period_end": "2021-10-13",
  "next_billing_date": "2021-10-15",
  "payment_method_id": "16fe4476-bff5-4fc9-8e93-164ad89c241a",
  "external_id": "2bfe4476-bff5-4fc9-8e93-164ad89c241e",
  "one_time_costs": [
    {
      "id": "3bae4476-bff5-4fc9-8e93-164ad89c241e"
    }
  ],
  "discounts": [
    {
      "id": "14fe4476-bff5-4fc9-8e93-164ad89c241e",
      "cycle_amounts_left": 1
    }
  ],
  "taxes": [
    {
      "id": "01fe4476-bff5-4fc9-8e93-164ad89c241e"
    }
  ]
  "additional_costs": [
    {
      "id": "00000000-0000-0000-0000-000000000001"
    }
  ]
}