# Registrar Suscripción

{% hint style="info" %}
Método: **POST**
{% endhint %}

{% hint style="success" %}
**Producción:** <https://api.payvalida.com/v4/subscriptions>
{% endhint %}

{% hint style="success" %}
**Sandbox:** [https://api-test.payvalida.com/v4/subscriptions](https://api-test.payvalida.com/v4/subscriptions/)
{% endhint %}

{% tabs %}
{% tab title="Request" %}

<table data-full-width="true"><thead><tr><th width="129">Campo</th><th width="119">Estructura</th><th width="89">Tipo</th><th width="112">Requerido</th><th>Descripción</th></tr></thead><tbody><tr><td>merchant</td><td><br></td><td>string</td><td>sí</td><td>Nombre asignado para el comercio en Payválida. Se entrega con las credenciales.</td></tr><tr><td>plan_id</td><td><br></td><td>string</td><td>sí</td><td>id del plan que se le asignará al cliente para activar la suscripción.</td></tr><tr><td>start_date</td><td></td><td>string</td><td>no</td><td>Fecha de inicio de la suscripción en formato DD/MM/AAAA. Si no se proporciona, se asignará la fecha de invocación. Esta fecha corresponde al primer pago y marca el comienzo de la frecuencia de pagos de la suscripción. Si el pago es con tarjeta de credito se  tomara esta fecha como la fecha de hoy.</td></tr><tr><td>checksum</td><td><br></td><td>string</td><td>sí</td><td>Cadena de comprobación con SHA512 (merchant + plan_id + FIXED_HASH).</td></tr><tr><td></td><td>customer</td><td>struct</td><td>sí</td><td>Estructura con la información de usuario a la que se le enviará la suscripción</td></tr><tr><td>email</td><td>customer</td><td>string</td><td>sí</td><td>Correo electrónico del cliente. Debe cumplir con el formato estándar de correo válido.</td></tr><tr><td>user_di</td><td>customer</td><td>string</td><td>sí</td><td>Número del documento de identidad del cliente.</td></tr><tr><td>type_di</td><td>customer</td><td>string</td><td>sí</td><td>Tipo del documento de identidad del cliente.</td></tr><tr><td>first_name</td><td>customer</td><td>string</td><td>sí</td><td>Nombre del cliente en el documento de identidad (no acepta caracteres especiales ni acentos).</td></tr><tr><td>last_name</td><td>customer</td><td>string</td><td>sí</td><td>Apellido del cliente en el documento de identidad (no acepta caracteres especiales ni acentos).</td></tr><tr><td>cellphone</td><td>customer</td><td>string</td><td>sí</td><td>Número de celular del cliente.  Debe llevar el indicativo del país.</td></tr><tr><td></td><td>credit_card_data</td><td>struct</td><td>no</td><td>Estructura para activar débito automático de tarjeta.</td></tr><tr><td>card_number</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td><a href="https://docs.payvalida.com/api-tarjeta/sample-cards">Número de la tarjeta.</a></td></tr><tr><td>cvv</td><td>credit_card_data</td><td>int</td><td>sí (débito automático activo)</td><td>Código de seguridad de la tarjeta. </td></tr><tr><td>expiration_date</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Fecha de expiración de la tarjeta en formato <strong>MM/AA.</strong></td></tr><tr><td>retries</td><td>credit_card_data</td><td>int</td><td>no</td><td><p>Define la cantidad de veces que se reintenta un pago en caso de ser fallido (ej. fondos insuficentes). Valor por defecto: 1.</p><p>Valores permitidos: entre 0 - 4.<br>Si es mayor a 1, se ejecutan los reintentos con un día de diferencia, siempre y cuando el procesador lo permita.</p></td></tr><tr><td>franchise</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td><a href="https://docs.payvalida.com/api-tarjeta/v/master/franquicias-de-tarjeta-de-credito">Define la franquicia de la tarjeta. </a></td></tr><tr><td>id_type</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td><a href="https://docs.payvalida.com/api-tarjeta/v/master/tipos-de-identificacion">Tipo de documento de identificación</a> de la persona que realiza la transacción.</td></tr><tr><td>id</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Número de documento de identificación de la persona que realiza la transacción.</td></tr><tr><td>holder_name</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Nombre del titular de la tarjeta, sin apellidos.</td></tr><tr><td>holder_last_name</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Apellidos del titular de la tarjeta.</td></tr><tr><td>email</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Dirección de correo electrónico de la persona que realiza la transacción.</td></tr><tr><td>phone</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Número telefónico de la persona que realiza la transacción sin indicativos.</td></tr><tr><td>ip</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Dirección IP del dispositivo origen de la transacción, del usuario final.</td></tr><tr><td>header_user_agent</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>header_user_agent de el navegador de el usuario.</td></tr><tr><td>line1</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Línea 1 asociada a la dirección de facturación del usuario.</td></tr><tr><td>line2</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Línea 2 asociada a la dirección de facturación del usuario.</td></tr><tr><td>line3</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Línea 3 asociada a la dirección de facturación del usuario.</td></tr><tr><td>country</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>País del usuario.</td></tr><tr><td>city</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Ciudad del usuario.</td></tr><tr><td>state</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Estado o departamento del usuario.</td></tr><tr><td>post_code</td><td>credit_card_data</td><td>string</td><td>sí (débito automático activo)</td><td>Código postal de usuario.</td></tr><tr><td>customer_id</td><td></td><td>string</td><td>no</td><td>Identificador único de un usuario con una suscripción existente. Al crear una nueva suscripción, puedes usar el customer_id para evitar enviar nuevamente la información del usuario y la tarjeta. Con el campo customer_id en el request las estructuras customer y credit_card_data no son requeridas.</td></tr></tbody></table>
{% endtab %}

{% tab title="Request (ejemplo)" %}

```bash
curl --location --request POST 'https://api-test.payvalida.com/v4/subscriptions' \
--header 'Content-Type: application/json' \
--data-raw '{
   "merchant":"kuanto",
   "plan_id":"50e25c83-12ba-442f-adf8-6d410b376045",
   "checksum":"d171f0254271b731d06b91ad97bb0ec284e5997c997597cc8068fc688cb94f6b7dbe6295531e01b52c67cbeb2eddfcfabe29ca12323f118d77239001ed411869",
   "start_date":"22/11/2024",
   "customer":{
      "first_name":"user-name",
      "last_name":"last-name",
      "user_di":"999999999",
      "type_di":"CC",
      "cellphone":"+57112321131331",
      "email":"user@example.com"
   }
}'
```

{% endtab %}

{% tab title="Request (ejemplo con débito automático)" %}

```bash
curl --location --request POST 'https://api-test.payvalida.com/v4/subscriptions' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchant": "test",
    "plan_id": "cb2aef2d-03b1-47eb-9ca3-1179a5f64127",
    "checksum": "05eb0782e16369b3d1738b907c887c0ae665b386c0180eed803a1b6cd1a0ca172ab64018c6bcfd2dfb4c52149cdcf2ad7af4868a8708a6fb28efc58ec3cc047e",
    "customer": {
        "first_name": "john",
        "last_name": "doe",
        "user_di": "888888888",
        "type_di": "CC",
        "cellphone": "+57300222222",
        "email": "johndoe@test.com"
    },
    "credit_card_data": {
        "card_number": "4111111111111111",
        "cvv": 123,
        "expiration_date": "12/26",
        "franchise": "VISA",
        "id_type": "CC",
        "id": "888888888",
        "holder_name": "john",
        "holder_last_name": "doe",
        "email": "johndoe@test.com",
        "phone": "3002222222",
        "ip": "1.1.1.1",
        "header_user_agent": "test-user-agent",
        "line1": "calle 123 # 12 - 23",
        "line2": "CASA",
        "line3": "CASA",
        "country": "Colombia",
        "city": "Medellin",
        "state": "Antioquia",
        "post_code": "050001"
    }
}'
```

{% endtab %}

{% tab title="Response" %}

<table data-full-width="true"><thead><tr><th width="128">Campo</th><th width="151">Estructura</th><th width="130">Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>CODE</td><td>-</td><td>string</td><td>Código de respuesta 0000 para OK.</td></tr><tr><td>DESC</td><td>-</td><td>string</td><td>Descripción de la respuesta.</td></tr><tr><td>DATA</td><td>-</td><td>string</td><td>Datos del registro</td></tr><tr><td>id</td><td>DATA</td><td>string</td><td>id generado para la suscripción</td></tr><tr><td>token</td><td>DATA(solo para debito automatico)</td><td>string</td><td>token generado para la transacción.</td></tr><tr><td>status</td><td>DATA</td><td>string</td><td>Estado en el que se encuentra la suscripción, puedes ver más detalles sobre los estados en el apartado de estados</td></tr><tr><td>id</td><td>DATA-CUSTOMER</td><td>string</td><td>id del cliente creado con la información suministrada</td></tr><tr><td>id</td><td>DATA-PLAN</td><td>string</td><td>id del plan suministrado para crear la suscripción</td></tr></tbody></table>
{% endtab %}

{% tab title="Response (ejemplo)" %}

```json
{
    "CODE": "0000",
    "DESC": "OK",
    "DATA": {
        "id": "b45fd212-2c26-4068-9807-2c9c6b8ac204",
        "start_date": "14/06/2023",
        "status": "ACTIVE",
        "plan": {
            "id": "50e25c83-12ba-442f-adf8-6d410b376045"
        },
        "customer": {
            "id": "b45fd212-2c26-4068-9807-2c9c6b8ac204"
        }
    }
}
```

{% endtab %}

{% tab title="Response (débito automático)" %}

```json
{
    "CODE": "0000",
    "DESC": "OK",
    "DATA": {
        "id": "c0b44586-bfef-4a58-92ca-d91d9201211d",
        "status": "ACTIVE",
        "token": "4106103912271111",
        "plan": {
            "id": "cb2aef2d-03b1-47eb-9ca3-1179a5f64127"
        },
        "customer": {
            "id": "1eb44956-208f-41f2-b8fa-acf9d0e2b4a0"
        }
    }
}
```

{% endtab %}

{% tab title="Cabeceras" %}

| Cabecera      | Valor            |
| ------------- | ---------------- |
| Content-Type  | application/json |
| {% endtab %}  |                  |
| {% endtabs %} |                  |

{% hint style="info" %}
Para los días que no existan en meses donde se debe realizar un pago, por ejemplo el día 31, el límite para realizar el pago de la suscripción será el último día de dicho mes.
{% endhint %}

## Ejemplos

* Go

```go
package main

import (
	"bytes"
	"crypto/sha512"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
	"strconv"
	"time"
)

type Payload struct {
	Merchant  string `json:"merchant"`
	PlanID    string `json:"plan_id"`
	Checksum  string `json:"checksum"`
	StartDate  string `json:"start_date"`
	Customer  struct {
		FirstName string `json:"first_name"`
		LastName  string `json:"last_name"`
		UserDI    string `json:"user_di"`
		TypeDI    string `json:"type_di"`
		Cellphone string `json:"cellphone"`
		Email     string `json:"email"`
	} `json:"customer"`
}

func main() {
	url := "https://api-test.payvalida.com/v4/subscriptions"

	// Prepare the request payload
	payload := Payload{
		Merchant:  "kuanto",
		PlanID:    "50e25c83-12ba-442f-adf8-6d410b376045",
		Checksum:  "d171f0254271b731d06b91ad97bb0ec284e5997c997597cc8068fc688cb94f6b7dbe6295531e01b52c67cbeb2eddfcfabe29ca12323f118d77239001ed411869",
		StartDate: "12/12/2024"
		Customer: struct {
			FirstName string `json:"first_name"`
			LastName  string `json:"last_name"`
			UserDI    string `json:"user_di"`
			TypeDI    string `json:"type_di"`
			Cellphone string `json:"cellphone"`
			Email     string `json:"email"`
		}{
			FirstName: "user-name",
			LastName:  "last-name",
			UserDI:    "999999999",
			TypeDI:    "CC",
			Cellphone: "+57112321131331",
			Email:     "user@example.com",
		},
	}

	// Create the checksum
	data := payload.Merchant + strconv. + payload.PlanID + "FIXED_HASH"
	checksum := calculateSHA512(data)

	// Update the checksum value in the payload
	payload.Checksum = checksum

	// Convert the payload to JSON
	requestBody, err := json.Marshal(payload)
	if err != nil {
		fmt.Println("Error marshaling request payload:", err)
		return
	}

	// Send the POST request
	resp, err := http.Post(url, "application/json", bytes.NewBuffer(requestBody))
	if err != nil {
		fmt.Println("Error sending request:", err)
		return
	}
	defer resp.Body.Close()

	// Read the response body
	responseBody, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("Error reading response body:", err)
		return
	}

	// Print the response body
	fmt.Println("Response Body:", string(responseBody))
}

func calculateSHA512(data string) string {
	hash := sha512.Sum512([]byte(data))
	return hex.EncodeToString(hash[:])
}

```

* PHP

```php
<?php

$url = 'https://api-test.payvalida.com/v4/subscriptions';

// Prepare the request payload
$payload = array(
    "merchant" => "kuanto",
    "plan_id" => "50e25c83-12ba-442f-adf8-6d410b376045",
    "checksum" => "d171f0254271b731d06b91ad97bb0ec284e5997c997597cc8068fc688cb94f6b7dbe6295531e01b52c67cbeb2eddfcfabe29ca12323f118d77239001ed411869",
    "start_date" => "12/12/2024",
    "customer" => array(
        "first_name" => "user-name",
        "last_name" => "last-name",
        "user_di" => "999999999",
        "type_di" => "CC",
        "cellphone" => "+57112321131331",
        "email" => "user@example.com"
    )
);

// Create the checksum
$data = $payload['merchant'] .  $payload['plan_id'] . 'FIXED_HASH';
$checksum = hash('sha512', $data);

// Update the checksum value in the payload
$payload['checksum'] = $checksum;

// Convert the payload to JSON
$requestBody = json_encode($payload);

// Set the request headers
$headers = array(
    'Content-Type: application/json'
);

// Initialize cURL
$ch = curl_init();

// Set cURL options
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestBody);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// Execute the cURL request
$response = curl_exec($ch);

// Check for cURL errors
if (curl_error($ch)) {
    echo 'Error: ' . curl_error($ch);
    exit;
}

// Close cURL
curl_close($ch);

// Print the response body
echo 'Response Body: ' . $response;

```

* Javascript

```javascript
const fetch = require('node-fetch');
const crypto = require('crypto');

const url = 'https://api-test.payvalida.com/v4/subscriptions';

// Prepare the request payload
const payload = {
  merchant: 'kuanto',
  plan_id: '50e25c83-12ba-442f-adf8-6d410b376045',
  checksum: 'd171f0254271b731d06b91ad97bb0ec284e5997c997597cc8068fc688cb94f6b7dbe6295531e01b52c67cbeb2eddfcfabe29ca12323f118d77239001ed411869',
  start_date: '12/12/2024',
  customer: {
    first_name: 'user-name',
    last_name: 'last-name',
    user_di: '999999999',
    type_di: 'CC',
    cellphone: '+57112321131331',
    email: 'user@example.com',
  },
};

// Create the checksum
const data = payload.merchant + payload.plan_id + 'FIXED_HASH';
const checksum = crypto.createHash('sha512').update(data).digest('hex');

// Update the checksum value in the payload
payload.checksum = checksum;

// Send the POST request
fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
})
  .then((response) => response.json())
  .then((data) => {
    console.log('Response Body:', data);
  })
  .catch((error) => {
    console.error('Error:', error);
  });

```

* Java

```java
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public class Main {

    public static void main(String[] args) {
        String url = "https://api-test.payvalida.com/v4/subscriptions";

        // Prepare the request payload
        String payload = "{\n" +
                "   \"merchant\":\"kuanto\",\n" +
                "   \"plan_id\":\"50e25c83-12ba-442f-adf8-6d410b376045\",\n" +
                "   \"checksum\":\"d171f0254271b731d06b91ad97bb0ec284e5997c997597cc8068fc688cb94f6b7dbe6295531e01b52c67cbeb2eddfcfabe29ca12323f118d77239001ed411869\",\n" +
                "   \"start_date\":\"12/12/2024\",\n" +
                "   \"customer\":{\n" +
                "      \"first_name\":\"user-name\",\n" +
                "      \"last_name\":\"last-name\",\n" +
                "      \"user_di\":\"999999999\",\n" +
                "      \"type_di\":\"CC\",\n" +
                "      \"cellphone\":\"+57112321131331\",\n" +
                "      \"email\":\"user@example.com\"\n" +
                "   }\n" +
                "}";

        // Create the checksum
        String data = "kuanto" + "50e25c83-12ba-442f-adf8-6d410b376045" + "FIXED_HASH";
        String checksum = getSHA512Checksum(data);

        // Update the checksum value in the payload
        payload = payload.replace("d171f0254271b731d06b91ad97bb0ec284e5997c997597cc8068fc688cb94f6b7dbe6295531e01b52c67cbeb2eddfcfabe29ca12323f118d77239001ed411869", checksum);

        try {
            // Create the HTTP connection
            URL apiUrl = new URL(url);
            HttpURLConnection connection = (HttpURLConnection) apiUrl.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Content-Type", "application/json");
            connection.setDoOutput(true);

            // Send the request payload
            try (OutputStream outputStream = connection.getOutputStream()) {
                byte[] input = payload.getBytes(StandardCharsets.UTF_8);
                outputStream.write(input, 0, input.length);
            }

            // Get the response
            try (BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
                StringBuilder response = new StringBuilder();
                String line;
                while ((line = reader.readLine()) != null) {
                    response.append(line);
                }
                System.out.println("Response Body: " + response.toString());
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    private static String getSHA512Checksum(String data) {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-512");
            byte[] hashBytes = digest.digest(data.getBytes(StandardCharsets.UTF_8));

            StringBuilder hexString = new StringBuilder();
            for (byte hashByte : hashBytes) {
                String hex = Integer.toHexString(0xff & hashByte);
                if (hex.length() == 1) {
                    hexString.append('0');
                }
                hexString.append(hex);
            }
            return hexString.toString();
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
        }
        return null;
    }
}

```

* Python&#x20;

```python
import requests
import hashlib
import json
import time

url = 'https://api-test.payvalida.com/v4/subscriptions'

# Prepare the request payload
payload = {
    "merchant": "kuanto",
    "plan_id": "50e25c83-12ba-442f-adf8-6d410b376045",
    "checksum": "d171f0254271b731d06b91ad97bb0ec284e5997c997597cc8068fc688cb94f6b7dbe6295531e01b52c67cbeb2eddfcfabe29ca12323f118d77239001ed411869",
    "start_date": "12/12/2024",
    "customer": {
        "first_name": "user-name",
        "last_name": "last-name",
        "user_di": "999999999",
        "type_di": "CC",
        "cellphone": "+57112321131331",
        "email": "user@example.com"
    }
}

# Create the checksum
data = payload['merchant'] + payload['plan_id'] + 'FIXED_HASH'
checksum = hashlib.sha512(data.encode()).hexdigest()

# Update the checksum value in the payload
payload['checksum'] = checksum

# Send the POST request
response = requests.post(url, json=payload)

# Print the response body
print('Response Body:', response.json())hin
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payvalida.com/api-suscripciones/suscripciones/registrar-suscripcion.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.