Crear un plan

Permite crear un precio para una suscripción recurrente con características específicas.

Crea un plan, también conocido como pago recurrente o price, al cuál se podrán suscribir tus clientes.

Definir la fecha de cobro

La fecha de cobro se define usando el objeto "recurring" el cuál a su vez contiene los siguientes parámetros:

  • interval:
    Es el intervalo de tiempo en el que se realizará el cobro.
    Únicamente puede ser “month” para mensual o “week” para semanal.

  • frequency:
    Es la frecuencia con la que se realizará el cobro.
    Por ejemplo:
    • Para un pago mensual tendrías que poner un “interval”: “month” y un “frequency”: 1
    • Para un pago bimestral tendrías que poner un “interval”: “month” y un “frequency”: 2
    • Para un pago quincenal (cada 2 semanas), tendrías que poner un “interval”: “week” y un “frequency”:2

  • repeat:
    Es para indicar si tiene una duración definida.
    Por ejemplo, si la suscripción únicamente va a durar 6 meses, tendrías que poner un “interval”: “month”, un “frequency”:1 y un “repeat”: 6

  • billing_day:
    Es el día específico en el que se realizarán los cobros automáticos a los suscriptores.
    Existen algunas restricciones, puedes consultar los valores disponibles en la sección "Valores disponibles para el parámetro billing_day” que se muestra abajo.

  • anchor_billing_on_first_payment:
    Este parámetro te permite indicar si quieres que el día de cobro sea el mismo que el día de pago de tu cliente.
    Consideraciones:
    • Únicamente acepta valores booleanos (true o false)
    • Si este valor es true entonces el “billing_day” tiene que ir vacío.
    • Aunque el “billing_day” se quede vacío, se tiene que enviar el array, ejemplo:
      "recurring" : {
                "interval":"month",
                "frequency": 1,
                "repeat": 0,
                "billing_day":[],
                "anchor_billing_on_first_payment": true,
                "grace_period_days":2
           }
      

  • grace_period_days:
    Cuando un cargo automático no es exitoso el estado del pago se convierte en “overdue”, por medio de este parámetro puedes extender el periodo de gracia en caso de que el apgo no sea exitoso, antes de que el estado cambie.

Valores disponibles para el parámetro “billing_day”

Los posibles valores disponibles para el parámetro “billing_day” dependen del valor asignado al parámetro “interval”.

Para un “interval”: “week”:
Los valores aceptados son los números del 1 al 7 en donde cada número representa cada día de la semana:

  • 1: Lunes
  • 2: Martes
  • 3: Miércoles
  • 4: Jueves
  • 5: Viernes
  • 6: Sábado
  • 7: Domingo

Ejemplo: Un "billing_day":[2] se cobrará cada semana los días martes.


Para un “interval”: “month”

Los valores disponibles son 1, 15 o 31, en donde:

  • 1: El 1ro de cada mes
  • 15: El 15 de cada mes.
  • 31: El último día del mes.

Para el día 31, en caso de que algún mes no tenga ese día, se cobrará el último día del mes.

Ejemplo: Si el día de cobro es el día 31: "billing_day":[31], el 31 de Enero se hará el cargo automático, el siguiente cargo se hará el 28 de Febrero, en Abril se hará el día 30, etc.


Para pagos quincenales
Lo que se pueden configurar son pagos cada 2 semanas en el mismo día, usando los parámetros “interval”:”week” y “frequency”:2, ejemplo:

"recurring" : {
          "interval":"week",
          "frequency": 2,
          "repeat": 0,
          "billing_day":[3],
          "anchor_billing_on_first_payment": false,
          "grace_period_days":2
     }

Esto indica que el cargo automático sería cada 2 semanas en Miércoles.


¿Que sucede si usas valores diferentes a los indicados?

El pago recurrente o suscripción se creará, pero al momento de suscribirse, en la sección donde normalmente se muestra el día de pago, se mostrará un valor genérico de esta forma:





Header parameters (parámetros del encabezado)

La siguiente tabla describe el esquema de los parámetros del encabezado.

Parámetro

Descripción

Tipo

Requerido / Opcional

Notas

Content-Type

Define el formato del objeto de la llamada

application/json

Requerido

Solicitud en formato JSON

Authorization

Especifica el token de acceso

String

Requerido

token de autenticación



Body parameters

Parámetro

Descripción

Tipo

Ejemplo

Requerido / Opcional

Notas

name

Nombre del plan.

String

“Membresía Gold”

Requerido

Máximo 256 caracteres.

description

Descripción del plan.

String

“Membresía mensual nivel gold”

Requerido

Máximo 256 caracteres.

description

Descripción del plan.

String

“Membresía mensual nivel gold”

Requerido

Máximo 256 caracteres.

recurring

Objeto con la información de la periodicidad del pago.

Objeto

Requerido

interval

Intervalo al que será cobrado el pago.

String

“month”

Requerido

Posibles valores: “week” o “month”.

frequency

Cada cuando se ejecutará el pago.

Integer

1

Requerido

Trabaja junto con el “interval”, ej. una frequency de 2 con un “interval” “month” hace referencia a un pago bimestral (cada dos meses).

repeat

Cuántas veces se ejecutará el ciclo de pago.

Integer

6

Opcional

Para duración indefinida se deja en 0 o se puede omitir.

Para duración indefinida se deja en 0 o se puede omitir. Si se define una duración específica el plan se cancelará automáticamente después de ese lapso de tiempo, ej. un “interval”:”month” con un “frequency”:1 y un “repeat”:6 indica un pago mensual con una duración de 6 meses.

billing_day

Día en que se realizará el cargo a la tarjeta.

Integer array

[15]

Requerido

Para un “interval”:”week” los valores aceptados son del 1 al 7.

Para un “interval”:”month” los valores aceptados son del 1 al 31.

anchor _billing _on_first _payment

Si se define como true el día de pago será el mismo día que el primer pago.

Booleano

false

Requerido

Si se pone como true, entonces el “billing_day” se deberá dejar vacío: [].

grace _period _days

Indica cuántos días le vas a dar a tu cliente para realizar el pago antes de que se marque como “overdue” (vencido).

Integer

[15]

Requerido

Para un “interval”:”week” los valores aceptados son del 1 al 7.

Para un “interval”:”month” los valores aceptados son del 1 al 31.

additional _information

Sirve para pedirle alguna información adicional a tus clientes.

Array

  •  ["Número de alumno",
  •  "Materia",
  •  "Turno",
  •  "Horario"]

Optional

Es un campo dinámico. El o los nombres que definas aparecerán en el formulario de suscripción.

Se permiten hasta 4 campos adicionales.

webhook_url

URL del endpoint que recibirá notificaciones webhook del link de pago.

String

“https://www. webhook.com”

Requerido

Es necesario proporcionar un webhook para que puedas recibir actualizaciones de tus planes, suscripiones o pagos.

redirect_urls

Objeto con las URLs para redirección del cliente después del pago.

Objeto

Requerido

Las URLs de redirección son necesarias para que puedas redirigir a tus clientes desde

success

URL a la que se redireccionará al cliente cuando el pago es exitoso.

String

“https://www. misitio.com /success”

Requerido

error

URL a la que se redireccionará al cliente cuando han fallado varios intentos.

String

“https://www. misitio.com /error”

Requerido

default

URL de la tienda virtual.

String

“https://www. misitio.com”

Requerido


Código de ejemplo

Ejemplo de una llamada.

El siguiente bloque de código muestra un ejemplo de la solicitud cURL:

curl --location 'https://api.payclip.com/prices' \
--header 'Authorization: Basic MTBkMTA2Y2QtMTI4Ny00MjI1LWE0ZWQtNzY3MWRkM2Y5ZDEzOjExNWYwMjE0LWJkZDgtNGY1ZS04ODRmLWVhMTM0YjVhNTUyNA==' \
--header 'Content-Type: application/json' \
--data '{
     "name":"Nombre del plan",
     "description":"Descripción del plan",
     "amount": 90.50,
     "recurring" : {
          "interval":"month",
          "frequency": 1,
          "repeat": 0,
          "billing_day":[15],
          "anchor_billing_on_first_payment": false,
          "grace_period_days":2
     },
    "additional_information":["Número de alumno", "Materia", "Turno", "Salón"], 
     "webhook_url":"https://webhook.com", 
     "redirect_urls" : {
          "success":"https://www.misitio.mx/success",
          "error":"https://www.misitio.mx/error",
          "default":"https://www.misitio.mx"
     }
}'

Ejemplo de un objeto de la respuesta

El siguiente objeto es una respuesta de éxito con código HTTP 201 OK:

{
    "id": "6e5a54aa-2987-4e87-8305-cfe5ea1e46ba",
    "name": "Nombre del plan",
    "description": "Descripción del plan",
    "amount": 90.50,
    "recurring": {
        "interval": "month",
        "frequency": 1,
        "repeat": 0,
        "billing_day": [
            15
        ],
        "anchor_billing_on_first_payment": false,
        "subscription_link":"https://pago.payclip.com/suscripcion/
6e5a54aa-2987-4e87-8305-cfe5ea1e46ba",
        "grace_period_days": 2
    },
    "status": "active",
    "additional_information": [
        "Número de alumno",
        "Materia",
        "Turno",
        "Salón"
    ],
    "webhook_url": "https://webhook.com",
    "created_at": "2024-04-10T06:41:45.485Z",
    "updated_at": "2024-04-10T06:41:45.485Z",
    "redirect_urls": {
        "success": "https://www.misitio.mx/success",
        "error": "https://www.misitio.mx/error",
        "default": "https://www.misitio.mx"
    }
}

Códigos de respuesta

La siguiente tabla contiene una lista de los códigos de respuesta y su asociación con algunos de los estados HTTP:

Estado HTTP

Error code

Mensaje

400

CL2201

Webhook URL format not valid

400

CL2201

Redirect.Success URL format not valid

400

CL2201

Redirect.Error URL format not valid

400

CL2202

Description field out of bound

400

CL2202

Name field out of bound

400

CL2202

Additional Information cannot take more than 4

400

CL2203

Name is null or empty

400

CL2203

Recurring Interval not valid

400

CL2204

Anchor Billing on First Payment is missing

400

CL2204

Billing day parameter is missing

400

CL2205

Billing day value not valid

400

CL2207

Billing day should be empty if Billing day proportional is set to true

400

CL2209

Grace period duration should be within a weeks time

400

CL2209

Grace period duration should be within a months time

400

CL2210

Billing day should contain some valid value if proportional is false

401

CL1501

Unauthorized

500

UN1800

"An error occurred: NullPointerException - null"


Ejemplo de una respuesta conteniendo un código de error en formato JSON. En este ejemplo se comparte el código de error en el campo “error_code”, la descripción en el campo “message” y dentro del objeto “detail” se comparte más información al respecto:

{
"error_code": "CL2203",
"message": "Bad Request",
"detail": [
  "Name is null or empty"
  ]
}



Realiza una llamada de prueba:

Language
Click Try It! to start a request and see the response here!