Saltar al contenido principal

/plan

Crear un plan

(POST /plan)

Permite dar de alta un plan en el sistema

Cuerpo de la petición(body)

  • external_id(string): Identificador único dado por el comercio, sirve para hacer un seguimiento sencillo de sus planes en base a identificadores de su sistema. Si no se especifica uno se usará el generado por nuestro sistema. external-id-123465
    • restricciones:
      • patrón: [\w-]
      • longitud mínima: 6
      • longitud máxima: 128
  • periodicity(string, required): Cadena de texto que indicará la periodicidad con la cual se cobrará el importe asociado al plan. Se indicará mediante un número seguido de cualquiera de las siguientes letras: "d", "w", "m", e "y" indicando días, semanas, meses y años respectivamente. 1m
    • restricciones:
      • patrón: [1-9](?:[0-9]+)?[dwmy]
  • name(string, required): Nombre identificador del plan. Subscription-100001
    • restricciones:
      • longitud máxima: 128
      • longitud mínima: 6
      • patrón: [\w\-\s]
  • description(string): Descripción del plan. Se recomienda utilizarlo para facilitar la identificación y gestión de los planes por parte del comercio. Test Subscription
    • restricciones:
      • longitud máxima: 256
    • longitud mínima: 6 _ valor por defecto: "" _ patrón: [\w\s\-\,\.]
  • amount:(integer, required): Importe fijo asociado al plan. Será una cadena de texto o un número entero de como máximo de 10 cifras, por ejemplo, "0000000100" o 100, ambas representaciones darán como resultado 1,00€ 100
    • restricciones:
      • longitud máxima: 10
      • longitud mínima: 1
      • valor mínimo: 1
      • valor máximo: 9999999999
  • currency(string, required): Moneda del importe. Esta código de tres letras indica el tipo de moneda, y por tanto los decimales, que tiene dicho importe, por ejemplo, 100 EUR == 1,00 EUR. Referencia: ISO 4217. EUR
  • fees(integer): Número de cuotas a cobrar desde la fecha de inicio y con la periodicidad indicada. Si no se indica un número de cuotas (ni fecha de expiración) la finalización de la suscripción queda indefinida. 12
    • restricciones:
      • valor mínimo: 1
      • valor por defecto: Null
  • start_date(string): Indica la fecha, a 1 día vista, en la que el plan entrará en vigor y se realizará el primer cobro. Si no se indica una fecha de comienzo entrará en vigor en el mismo día, por ejemplo, Si estamos a 2016-01-25 solo se podrán crear planes con fechas superiores o iguales a 2016-01-26. 2016-01-26
    • restricciones:
      • formato: yyyy-mm-dd
      • valor por defecto: El día siguiente al de la petición
  • expired_at(string): Fecha en la que el plan quedará desactivado y no se realizarán más cobros al cliente. La fecha de expiración prevalecerá por encima de la fecha calculada desde la fecha de comienzo, el número de cuotas y la periodicidad, por ejemplo, dada una fecha de inicio: 2016-01-01, un número de cuotas: 2, una periodicidad: 1m y una fecha de expiración: 2016-01-27, en Febrero no se pasará el cobro que correspondería según el número de cuotas 2016-07-24
    • restricciones:
      • formato: yyyy-mm-dd
      • valor por defecto: Null
  • customer(object, required): Información asociada al cliente y necesaria independientemente del método de pago escogido
    • reference(string): Identificador del cliente, otorgado por el comercio, y que sirve de referencia contra sus sistemas reference-client-123465
      • restricciones:
        • patrón: [\w-{}]
        • longitud máxima: 255
        • longitud mínima: 1
        • valor por defecto: Identificador único (uuid4)
    • name(string, required): Nombre completo del cliente John Doe Sullivan
      • restricciones:
        • patrón: [\w\s-',.]
        • longitud máxima: 255
        • longitud mínima: 1
    • taxid(string, required): Identificación fiscal del cliente (NIF o CIF) 27802534L
      • patrón: [0-9A-Z]
      • longitud mínima: 3
      • longitud máxima: 15
  • method(object, required): Información asociada al método de pago
    • type(string): Tipo de método
      • debit
      • card
    • token(string): Identificador de la tarjeta. Este campo es obligatorio si el método es card. card-token-123456
      • restricciones:
        • patrón: [\w-]
        • longitud mínima: 6
        • longitud máxima: 128
    • iban(string): Identificador de la cuenta bancaria. Obligatorio si el método escogido es debit ES42587462354158786693215
      • restricciones:
        • patrón: [A-Z]2[0-9A-Z]32
        • longitud mínima: 14
        • longitud máxima: 34
    • reference(string): Identificador de referencia bancaria. Utiliza un sistema de plantillas basado en etiquetas que aluden a información perteneciente al plan u otros valores como la fecha. Código de referencia: {amount}{currency} {day} {month_name} {year} Las etiquetas disponibles son: _ {amount}: Importe _ {currency}: Código de la moneda _ {recurrence}: Periodicidad del plan, por ejemplo, semanal, mensual, trimestral o anual _ {year}: Año en formato YYYY, por ejemplo, 2017 _ {month}: Mes en formato MM, por ejemplo, 05 _ {month_name}: Nombre del mes, por ejemplo, January, February, ... _ {day}: Día en formato DD, por ejemplo, 05 _ {customer_id}: Identificador del cliente asociado al plan, se corresponse con el campo reference del objeto customer _ restricciones: _ patron: [\w-{}\s] _ longitud máxima: 255 _ longitud mínima: 6 * valor por defecto: {amount} {currency} {day} {month_name} {year}
    • mandate(object): Información relativa al mandato. Toda esta información es obligatoria si el método escogido es debit
      • signed_at(string): Fecha y hora de firma del mandato 2016-01-25 14:06:55
        • restricciones:
          • formato: yyyy-mm-dd HH:MM:SS
      • reference(string): Identificador del mandato, otorgada por el comercio, y que sirve de referencia contra sus sistemas reference-id-12456
        • restricciones:
          • patron: [\w-]
          • longitud máxima: 64
          • longitud mínima: 1
      • scheme(string): Tipo adeudo directo SEPA
        • CORE
  • custom_data(object): Información adicional a incluir junto con el plan y que será devuelta como parte del mismo en las diferentes operaciones {'key1': 'val1', 'key2': 'val2'}
    • restricciones:
      • valor por defecto: Null

Importante: No se podrán crear planes con fechas anteriores al día de hoy.

Ej. Cuenta bancaria (debit)

{
"key": "{{api-key}}",
"resource": "{{resource-key}}",
"nonce": "1234567890",
"mode": "sha256",
"payload": {
"periodicity": "1m",
"external_id": "external-reference-123456",
"amount": 100,
"currency": "eur",
"fees": 12,
"name": "12654-playstation-subscription",
"description": "Annual playstation subscription",
"start_date": "2016-01-28",
"expired_at": "2017-07-28",
"customer": {
"reference": "client-123465",
"name": "John Doe Sullivan",
"taxid": "29724381D"
},
"method": {
"type": "debit",
"iban": "ES1234567891234567891234",
"mandate": {
"signed_at": "2016-01-28 14:06:55",
"reference": "client-reference-123465",
"scheme": "core"
}
},
"custom_data": {
"dummy": "foo"
}
}
}

Ej. Tarjeta tokenizada (card)

{
"key": "{{api-key}}",
"resource": "{{resource-key}}",
"nonce": "1234567890",
"mode": "sha256",
"payload": {
"periodicity": "1m",
"external_id": "external-reference-123456",
"amount": 100,
"currency": "eur",
"fees": 12,
"name": "12654-playstation-subscription",
"description": "Annual playstation subscription",
"start_date": "2016-01-25",
"expired_at": "2016-01-25",
"customer": {
"reference": "client-123465",
"name": "John Doe Sullivan",
"taxid": "29724381D"
},
"method": {
"type": "card",
"token": "card-token-123456"
},
"custom_data": {
"dummy": "foo"
}
}
}

Respuesta - success

  • plan_id(string): Identificador del plan necesario para poder efectuar acciones contra él.
{
"description": "Unknown",
"code": "X-XXXX",
"type": "unknown",
"request_id": null,
"detail": "plan_created",
"uuid": "6041e2c2-ef1a-4aaf-a5be-b892da6ec0bd",
"payload": {
"amount": 100,
"fees": 12,
"description": "Annual playstation subscription",
"name": "12654-playstation-subscription",
"expired_at": null,
"plan_id": "5976f935c928580001cc5dd7",
"custom_data": {
"dummy": "foo"
},
"method": {
"token": "card-token-123456",
"type": "card"
},
"periodicity": "1m",
"resource": "example-resource-key",
"start_date": "2016-01-25",
"currency": "EUR",
"deleted_at": null,
"customer": {
"taxid": "29724381D",
"reference": "client-123465",
"name": "John Doe Sullivan"
},
"external_id": "external-reference-123456"
}
}