/plan

Create a Plan

(POST /plan)

Allows you to register a plan in the system.

Request Body

external_id(string): Unique identifier given by the merchant, used for easy tracking of their plans based on their system identifiers. If not specified, a system-generated identifier will be used. external-id-123465
- restrictions:
  - pattern: [\w-]
  - minimum length: 6
  - maximum length: 128
periodicity(string, required): Text string indicating the periodicity with which the amount associated with the plan will be charged. It should be indicated by a number followed by any of the following letters: "d", "w", "m", and "y" indicating days, weeks, months, and years respectively. 1m
- restrictions:
  - pattern: [1-9](?:[0-9]+)?[dwmy]
name(string, required): Identifier name for the plan. Subscription-100001
- restrictions:
  - maximum length: 128
  - minimum length: 6
  - pattern: [\w\-\s]
description(string): Description of the plan. It is recommended to use it to facilitate identification and management of plans by the merchant. Test Subscription
- restrictions:
  - maximum length: 256
  - minimum length: 6
  - default value: ""
  - pattern: [\w\s\-\,\.]
amount(integer, required): Fixed amount associated with the plan. It will be a text string or an integer with a maximum of 10 digits, for example, "0000000100" or 100, both representations will result in 1.00€ 100
- restrictions:
  - maximum length: 10
  - minimum length: 1
  - minimum value: 1
  - maximum value: 9999999999
currency(string, required): Currency of the amount. This three-letter code indicates the type of currency and therefore the decimals that the amount has, for example, 100 EUR == 1.00 EUR. Reference: ISO 4217. EUR
fees(integer): Number of installments to be charged from the start date with the indicated periodicity. If the number of installments (or expiration date) is not indicated, the subscription will end indefinitely. 12
- restrictions:
  - minimum value: 1
  - default value: Null
start_date(string): Indicates the date, one day ahead, when the plan will come into effect and the first charge will occur. If no start date is indicated, it will come into effect on the same day. For example, if we are on 2016-01-25, only plans with dates equal to or greater than 2016-01-26 can be created. 2016-01-26
- restrictions:
  - format: yyyy-mm-dd
  - default value: The day after the request
expired_at(string): Date when the plan will be deactivated and no further charges will be made to the customer. The expiration date will take precedence over the date calculated from the start date, the number of installments, and the periodicity. For example, given a start date of: 2016-01-01, a number of installments of 2, and a periodicity of 1m, and an expiration date of: 2016-01-27, in February the corresponding charge will not be made based on the number of installments 2016-07-24
- restrictions:
  - format: yyyy-mm-dd
  - default value: Null
customer(object, required): Information associated with the customer, necessary regardless of the payment method chosen.
- reference(string): Customer identifier provided by the merchant, which serves as a reference against their systems. reference-client-123465
  - restrictions:
    - pattern: [\w-{}]
    - maximum length: 255
    - minimum length: 1
    - default value: Unique identifier (uuid4)
- name(string, required): Full name of the customer John Doe Sullivan
  - restrictions:
    - pattern: [\w\s-',.]
    - maximum length: 255
    - minimum length: 1
- taxid(string, required): Tax identification of the customer (NIF or CIF) 27802534L
  - pattern: [0-9A-Z]
  - minimum length: 3
  - maximum length: 15
method(object, required): Information associated with the payment method.
- type(string): Type of method
  - debit
  - card
- token(string): Identifier of the card. This field is mandatory if the method is card. card-token-123456
  - restrictions:
    - pattern: [\w-]
    - minimum length: 6
    - maximum length: 128
- iban(string): Identifier of the bank account. Mandatory if the chosen method is debit ES42587462354158786693215
  - restrictions:
    - pattern: [A-Z]2[0-9A-Z]32
    - minimum length: 14
    - maximum length: 34
- reference(string): Bank reference identifier. Uses a template-based system referring to information belonging to the plan or other values such as the date. Reference code: {amount}{currency} {day} {month_name} {year} The available tags are:
  - {amount}: Amount
  - {currency}: Currency code
  - {recurrence}: Plan periodicity, e.g., weekly, monthly, quarterly, or annually
  - {year}: Year in YYYY format, e.g., 2017
  - {month}: Month in MM format, e.g., 05
  - {month_name}: Month name, e.g., January, February, ...
  - {day}: Day in DD format, e.g., 05
    - {customer_id}: Identifier of the customer associated with the plan, corresponding to the reference field of the customer object. _ restrictions: _ pattern: [\w-{}\s] _ maximum length: 255 _ minimum length: 6 * default value: {amount} {currency} {day} {month_name} {year}
- mandate(object): Information related to the mandate. All this information is mandatory if the chosen method is debit.
  - signed_at(string): Date and time of signing the mandate 2016-01-25 14:06:55
    - restrictions:
      - format: yyyy-mm-dd HH:MM:SS
  - reference(string): Identifier of the mandate, provided by the merchant, and serves as a reference against their systems reference-id-12456
    - restrictions:
      - pattern: [\w-]
      - maximum length: 64
      - minimum length: 1
  - scheme(string): Type of SEPA direct debit
    - CORE
custom_data(object): Additional information to include with the plan and that will be returned as part of it in the different operations {'key1': 'val1', 'key2': 'val2'}
- restrictions:
  - default value: Null

Important: Plans cannot be created with dates earlier than today.

Bank Account Example (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"
    }
  }
}

Tokenized Card Example

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

Response - Success

plan_id (string): The identifier of the plan necessary to perform actions against it.

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

Create a Plan​

Request Body​

Bank Account Example (debit)​

Tokenized Card Example​

Response - Success​

Create a Plan

Request Body

Bank Account Example (debit)

Tokenized Card Example

Response - Success