Crear suscripción

curl --request POST \
  --url https://tapipay-facade.dev.tapila.cloud/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-authorization-token: <api-key>' \
  --data '
{
  "externalSubscriptionId": "<string>",
  "amount": 1.01,
  "intervalCount": 2,
  "startDate": "2023-12-25",
  "externalClientId": "<string>",
  "currency": "MXN",
  "totalCycles": 2,
  "endDate": "2023-12-25",
  "description": "<string>",
  "productName": "<string>",
  "allowOverduePayment": true,
  "enforcePaymentOrder": false,
  "autopay": false,
  "paymentMethods": [],
  "additionalData": {}
}
'

import requests

url = "https://tapipay-facade.dev.tapila.cloud/subscriptions"

payload = {
    "externalSubscriptionId": "<string>",
    "amount": 1.01,
    "intervalCount": 2,
    "startDate": "2023-12-25",
    "externalClientId": "<string>",
    "currency": "MXN",
    "totalCycles": 2,
    "endDate": "2023-12-25",
    "description": "<string>",
    "productName": "<string>",
    "allowOverduePayment": True,
    "enforcePaymentOrder": False,
    "autopay": False,
    "paymentMethods": [],
    "additionalData": {}
}
headers = {
    "x-api-key": "<api-key>",
    "x-authorization-token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<api-key>',
    'x-authorization-token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    externalSubscriptionId: '<string>',
    amount: 1.01,
    intervalCount: 2,
    startDate: '2023-12-25',
    externalClientId: '<string>',
    currency: 'MXN',
    totalCycles: 2,
    endDate: '2023-12-25',
    description: '<string>',
    productName: '<string>',
    allowOverduePayment: true,
    enforcePaymentOrder: false,
    autopay: false,
    paymentMethods: [],
    additionalData: {}
  })
};

fetch('https://tapipay-facade.dev.tapila.cloud/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://tapipay-facade.dev.tapila.cloud/subscriptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'externalSubscriptionId' => '<string>',
    'amount' => 1.01,
    'intervalCount' => 2,
    'startDate' => '2023-12-25',
    'externalClientId' => '<string>',
    'currency' => 'MXN',
    'totalCycles' => 2,
    'endDate' => '2023-12-25',
    'description' => '<string>',
    'productName' => '<string>',
    'allowOverduePayment' => true,
    'enforcePaymentOrder' => false,
    'autopay' => false,
    'paymentMethods' => [
        
    ],
    'additionalData' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>",
    "x-authorization-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://tapipay-facade.dev.tapila.cloud/subscriptions"

	payload := strings.NewReader("{\n  \"externalSubscriptionId\": \"<string>\",\n  \"amount\": 1.01,\n  \"intervalCount\": 2,\n  \"startDate\": \"2023-12-25\",\n  \"externalClientId\": \"<string>\",\n  \"currency\": \"MXN\",\n  \"totalCycles\": 2,\n  \"endDate\": \"2023-12-25\",\n  \"description\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"allowOverduePayment\": true,\n  \"enforcePaymentOrder\": false,\n  \"autopay\": false,\n  \"paymentMethods\": [],\n  \"additionalData\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("x-authorization-token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://tapipay-facade.dev.tapila.cloud/subscriptions")
  .header("x-api-key", "<api-key>")
  .header("x-authorization-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalSubscriptionId\": \"<string>\",\n  \"amount\": 1.01,\n  \"intervalCount\": 2,\n  \"startDate\": \"2023-12-25\",\n  \"externalClientId\": \"<string>\",\n  \"currency\": \"MXN\",\n  \"totalCycles\": 2,\n  \"endDate\": \"2023-12-25\",\n  \"description\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"allowOverduePayment\": true,\n  \"enforcePaymentOrder\": false,\n  \"autopay\": false,\n  \"paymentMethods\": [],\n  \"additionalData\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://tapipay-facade.dev.tapila.cloud/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["x-authorization-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalSubscriptionId\": \"<string>\",\n  \"amount\": 1.01,\n  \"intervalCount\": 2,\n  \"startDate\": \"2023-12-25\",\n  \"externalClientId\": \"<string>\",\n  \"currency\": \"MXN\",\n  \"totalCycles\": 2,\n  \"endDate\": \"2023-12-25\",\n  \"description\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"allowOverduePayment\": true,\n  \"enforcePaymentOrder\": false,\n  \"autopay\": false,\n  \"paymentMethods\": [],\n  \"additionalData\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "subscriptionId": "<string>",
    "externalSubscriptionId": "<string>",
    "amount": 123,
    "currency": "MXN",
    "intervalCount": 123,
    "startDate": "2023-12-25",
    "billingDay": {
      "day": 16,
      "month": 6
    },
    "enforcePaymentOrder": true,
    "autopay": true,
    "createdAt": "2023-11-07T05:31:56Z",
    "totalCycles": 123,
    "endDate": "2023-12-25",
    "paymentMethods": [],
    "paymentUrl": "<string>",
    "contact": {
      "contactId": "<string>",
      "externalClientId": "<string>",
      "createdInline": true
    },
    "product": {
      "productId": "<string>",
      "name": "<string>",
      "active": true,
      "createdInline": true
    }
  },
  "requestId": "<string>"
}

{
  "error": {
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>"
      }
    ]
  },
  "requestId": "<string>"
}

{
  "error": {
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>"
      }
    ]
  },
  "requestId": "<string>"
}

{
  "error": {
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>"
      }
    ]
  },
  "requestId": "<string>"
}

{
  "error": {
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>"
      }
    ]
  },
  "requestId": "<string>"
}

POST

subscriptions

Crear suscripción

curl --request POST \
  --url https://tapipay-facade.dev.tapila.cloud/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-authorization-token: <api-key>' \
  --data '
{
  "externalSubscriptionId": "<string>",
  "amount": 1.01,
  "intervalCount": 2,
  "startDate": "2023-12-25",
  "externalClientId": "<string>",
  "currency": "MXN",
  "totalCycles": 2,
  "endDate": "2023-12-25",
  "description": "<string>",
  "productName": "<string>",
  "allowOverduePayment": true,
  "enforcePaymentOrder": false,
  "autopay": false,
  "paymentMethods": [],
  "additionalData": {}
}
'

import requests

url = "https://tapipay-facade.dev.tapila.cloud/subscriptions"

payload = {
    "externalSubscriptionId": "<string>",
    "amount": 1.01,
    "intervalCount": 2,
    "startDate": "2023-12-25",
    "externalClientId": "<string>",
    "currency": "MXN",
    "totalCycles": 2,
    "endDate": "2023-12-25",
    "description": "<string>",
    "productName": "<string>",
    "allowOverduePayment": True,
    "enforcePaymentOrder": False,
    "autopay": False,
    "paymentMethods": [],
    "additionalData": {}
}
headers = {
    "x-api-key": "<api-key>",
    "x-authorization-token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<api-key>',
    'x-authorization-token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    externalSubscriptionId: '<string>',
    amount: 1.01,
    intervalCount: 2,
    startDate: '2023-12-25',
    externalClientId: '<string>',
    currency: 'MXN',
    totalCycles: 2,
    endDate: '2023-12-25',
    description: '<string>',
    productName: '<string>',
    allowOverduePayment: true,
    enforcePaymentOrder: false,
    autopay: false,
    paymentMethods: [],
    additionalData: {}
  })
};

fetch('https://tapipay-facade.dev.tapila.cloud/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://tapipay-facade.dev.tapila.cloud/subscriptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'externalSubscriptionId' => '<string>',
    'amount' => 1.01,
    'intervalCount' => 2,
    'startDate' => '2023-12-25',
    'externalClientId' => '<string>',
    'currency' => 'MXN',
    'totalCycles' => 2,
    'endDate' => '2023-12-25',
    'description' => '<string>',
    'productName' => '<string>',
    'allowOverduePayment' => true,
    'enforcePaymentOrder' => false,
    'autopay' => false,
    'paymentMethods' => [
        
    ],
    'additionalData' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>",
    "x-authorization-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://tapipay-facade.dev.tapila.cloud/subscriptions"

	payload := strings.NewReader("{\n  \"externalSubscriptionId\": \"<string>\",\n  \"amount\": 1.01,\n  \"intervalCount\": 2,\n  \"startDate\": \"2023-12-25\",\n  \"externalClientId\": \"<string>\",\n  \"currency\": \"MXN\",\n  \"totalCycles\": 2,\n  \"endDate\": \"2023-12-25\",\n  \"description\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"allowOverduePayment\": true,\n  \"enforcePaymentOrder\": false,\n  \"autopay\": false,\n  \"paymentMethods\": [],\n  \"additionalData\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("x-authorization-token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://tapipay-facade.dev.tapila.cloud/subscriptions")
  .header("x-api-key", "<api-key>")
  .header("x-authorization-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalSubscriptionId\": \"<string>\",\n  \"amount\": 1.01,\n  \"intervalCount\": 2,\n  \"startDate\": \"2023-12-25\",\n  \"externalClientId\": \"<string>\",\n  \"currency\": \"MXN\",\n  \"totalCycles\": 2,\n  \"endDate\": \"2023-12-25\",\n  \"description\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"allowOverduePayment\": true,\n  \"enforcePaymentOrder\": false,\n  \"autopay\": false,\n  \"paymentMethods\": [],\n  \"additionalData\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://tapipay-facade.dev.tapila.cloud/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["x-authorization-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalSubscriptionId\": \"<string>\",\n  \"amount\": 1.01,\n  \"intervalCount\": 2,\n  \"startDate\": \"2023-12-25\",\n  \"externalClientId\": \"<string>\",\n  \"currency\": \"MXN\",\n  \"totalCycles\": 2,\n  \"endDate\": \"2023-12-25\",\n  \"description\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"allowOverduePayment\": true,\n  \"enforcePaymentOrder\": false,\n  \"autopay\": false,\n  \"paymentMethods\": [],\n  \"additionalData\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "subscriptionId": "<string>",
    "externalSubscriptionId": "<string>",
    "amount": 123,
    "currency": "MXN",
    "intervalCount": 123,
    "startDate": "2023-12-25",
    "billingDay": {
      "day": 16,
      "month": 6
    },
    "enforcePaymentOrder": true,
    "autopay": true,
    "createdAt": "2023-11-07T05:31:56Z",
    "totalCycles": 123,
    "endDate": "2023-12-25",
    "paymentMethods": [],
    "paymentUrl": "<string>",
    "contact": {
      "contactId": "<string>",
      "externalClientId": "<string>",
      "createdInline": true
    },
    "product": {
      "productId": "<string>",
      "name": "<string>",
      "active": true,
      "createdInline": true
    }
  },
  "requestId": "<string>"
}

{
  "error": {
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>"
      }
    ]
  },
  "requestId": "<string>"
}

{
  "error": {
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>"
      }
    ]
  },
  "requestId": "<string>"
}

{
  "error": {
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>"
      }
    ]
  },
  "requestId": "<string>"
}

{
  "error": {
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>"
      }
    ]
  },
  "requestId": "<string>"
}

Autorizaciones

x-api-key

string

header

requerido

API key del API Gateway de Tapi. Requerida en todas las operaciones. Distinta por ambiente (desarrollo, homologación, producción).

x-authorization-token

string

header

requerido

Token TAPI JWT. Requerido en todas las operaciones. Se envía sin prefijo "Bearer". Ej: x-authorization-token: eyJhbGci...

Encabezados

Idempotency-Key

string

Clave de idempotencia (opcional). Se usa como llave única (externalRequestId) de la suscripción. El externalRequestId es una llave permanente sin TTL (constraint UNIQUE en el OFU). Una request repetida con la misma key devuelve error 409 RESOURCE_CONFLICT (no es replay/idempotencia clásica; es rechazo de duplicado por constraint UNIQUE). Si no se envía, el backend genera un externalRequestId único. Ver ADR-004 v1.1 para detalles de semántica.

Cuerpo

application/json

externalSubscriptionId

string

requerido

Llave natural de la suscripción. Única por organización.

amount

number

requerido

Monto por ciclo en pesos (hasta 2 decimales, mínimo 0.01)

Rango requerido: x >= 0.01Debe ser un múltiplo de 0.01

intervalUnit

enum<string>

requerido

Unidad del intervalo (day, week, month, year)

Opciones disponibles:

day,

week,

month,

year

intervalCount

integer

requerido

Cantidad de unidades por ciclo

Rango requerido: x >= 1

startDate

string<date>

requerido

Fecha de inicio de la suscripción

externalClientId

string

Identificador del deudor (externalClientId o contactData, no ambos).

contactData

object

Datos del deudor inline (alternativa a externalClientId)

Show child attributes

currency

enum<string>

predeterminado:MXN

Código de moneda ISO 4217. Whitelist de monedas aceptadas por la Facade. Si no se envía, se usa el default de la organización (fallback: MXN). Si se envía un valor fuera de este whitelist, la Facade devuelve 400 INVALID_REQUEST.

Opciones disponibles:

MXN,

ARS,

PEN,

COP,

CLP,

USD

totalCycles

integer

Total de ciclos. Mutuamente excluyente con endDate.

Rango requerido: x >= 1

endDate

string<date>

Fecha de fin de la suscripción. Mutuamente excluyente con totalCycles.

billingDay

object

Override del día de cobro. Por default se infiere del startDate.

Show child attributes

description

string

productName

string

Nombre del producto a asociar (opcional). Se resuelve por name en el OFU o se crea inline si no existe. Identificado por name único por companyCode.

allowOverduePayment

boolean

predeterminado:true

enforcePaymentOrder

boolean

predeterminado:false

Si true, el deudor debe pagar en orden cronológico

autopay

boolean

predeterminado:false

paymentMethods

enum<string>[]

Opciones disponibles:

CASH,

CARD,

TRANSFER,

WALLET,

BANK_TRANSFER

additionalData

object

Respuesta

Suscripción creada

data

object

Show child attributes

requestId

string

Listar suscripciones Obtener suscripción

Contacts

Products

Debts

Subscriptions

Payment Links

Crear suscripción

Autorizaciones

Encabezados

Cuerpo

Respuesta