Crear un plan

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:

Dicho de otra forma, todo funcionará correctamente con cualquier valor, solo que no se mostrará la fecha de pago exacta.

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"
  ]
}

Llamada de prueba

Puedes realizar una llamada de prueba llenando los campos necesarios en el formulario que se muestra abajo.

Asegúrate de poner tu token de autenticación en el campo "Header: Autorization" del widget localizado a tu derecha: