Crear link de pago

curl --request POST \
  --url https://tapipay-facade.dev.tapila.cloud/payment-links \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-authorization-token: <api-key>' \
  --data '
{
  "amount": 1.01,
  "description": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z",
  "currency": "MXN",
  "externalPaymentLinkId": "<string>",
  "successUrl": "<string>",
  "singleUse": true,
  "metadata": {},
  "externalClientId": "<string>",
  "productName": "<string>",
  "identifierValue": "<string>",
  "additionalData": {}
}
'

import requests

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

payload = {
    "amount": 1.01,
    "description": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "currency": "MXN",
    "externalPaymentLinkId": "<string>",
    "successUrl": "<string>",
    "singleUse": True,
    "metadata": {},
    "externalClientId": "<string>",
    "productName": "<string>",
    "identifierValue": "<string>",
    "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({
    amount: 1.01,
    description: '<string>',
    expiresAt: '2023-11-07T05:31:56Z',
    currency: 'MXN',
    externalPaymentLinkId: '<string>',
    successUrl: '<string>',
    singleUse: true,
    metadata: {},
    externalClientId: '<string>',
    productName: '<string>',
    identifierValue: '<string>',
    additionalData: {}
  })
};

fetch('https://tapipay-facade.dev.tapila.cloud/payment-links', 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/payment-links",
  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([
    'amount' => 1.01,
    'description' => '<string>',
    'expiresAt' => '2023-11-07T05:31:56Z',
    'currency' => 'MXN',
    'externalPaymentLinkId' => '<string>',
    'successUrl' => '<string>',
    'singleUse' => true,
    'metadata' => [
        
    ],
    'externalClientId' => '<string>',
    'productName' => '<string>',
    'identifierValue' => '<string>',
    '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/payment-links"

	payload := strings.NewReader("{\n  \"amount\": 1.01,\n  \"description\": \"<string>\",\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"currency\": \"MXN\",\n  \"externalPaymentLinkId\": \"<string>\",\n  \"successUrl\": \"<string>\",\n  \"singleUse\": true,\n  \"metadata\": {},\n  \"externalClientId\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"identifierValue\": \"<string>\",\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/payment-links")
  .header("x-api-key", "<api-key>")
  .header("x-authorization-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 1.01,\n  \"description\": \"<string>\",\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"currency\": \"MXN\",\n  \"externalPaymentLinkId\": \"<string>\",\n  \"successUrl\": \"<string>\",\n  \"singleUse\": true,\n  \"metadata\": {},\n  \"externalClientId\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"identifierValue\": \"<string>\",\n  \"additionalData\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"amount\": 1.01,\n  \"description\": \"<string>\",\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"currency\": \"MXN\",\n  \"externalPaymentLinkId\": \"<string>\",\n  \"successUrl\": \"<string>\",\n  \"singleUse\": true,\n  \"metadata\": {},\n  \"externalClientId\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"identifierValue\": \"<string>\",\n  \"additionalData\": {}\n}"

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

{
  "data": {
    "paymentLinkId": "<string>",
    "amount": 123,
    "currency": "MXN",
    "description": "<string>",
    "singleUse": true,
    "paymentUrl": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "externalPaymentLinkId": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "successUrl": "<string>",
    "metadata": {},
    "identifierValue": "<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

payment-links

Crear link de pago

curl --request POST \
  --url https://tapipay-facade.dev.tapila.cloud/payment-links \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-authorization-token: <api-key>' \
  --data '
{
  "amount": 1.01,
  "description": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z",
  "currency": "MXN",
  "externalPaymentLinkId": "<string>",
  "successUrl": "<string>",
  "singleUse": true,
  "metadata": {},
  "externalClientId": "<string>",
  "productName": "<string>",
  "identifierValue": "<string>",
  "additionalData": {}
}
'

import requests

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

payload = {
    "amount": 1.01,
    "description": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "currency": "MXN",
    "externalPaymentLinkId": "<string>",
    "successUrl": "<string>",
    "singleUse": True,
    "metadata": {},
    "externalClientId": "<string>",
    "productName": "<string>",
    "identifierValue": "<string>",
    "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({
    amount: 1.01,
    description: '<string>',
    expiresAt: '2023-11-07T05:31:56Z',
    currency: 'MXN',
    externalPaymentLinkId: '<string>',
    successUrl: '<string>',
    singleUse: true,
    metadata: {},
    externalClientId: '<string>',
    productName: '<string>',
    identifierValue: '<string>',
    additionalData: {}
  })
};

fetch('https://tapipay-facade.dev.tapila.cloud/payment-links', 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/payment-links",
  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([
    'amount' => 1.01,
    'description' => '<string>',
    'expiresAt' => '2023-11-07T05:31:56Z',
    'currency' => 'MXN',
    'externalPaymentLinkId' => '<string>',
    'successUrl' => '<string>',
    'singleUse' => true,
    'metadata' => [
        
    ],
    'externalClientId' => '<string>',
    'productName' => '<string>',
    'identifierValue' => '<string>',
    '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/payment-links"

	payload := strings.NewReader("{\n  \"amount\": 1.01,\n  \"description\": \"<string>\",\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"currency\": \"MXN\",\n  \"externalPaymentLinkId\": \"<string>\",\n  \"successUrl\": \"<string>\",\n  \"singleUse\": true,\n  \"metadata\": {},\n  \"externalClientId\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"identifierValue\": \"<string>\",\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/payment-links")
  .header("x-api-key", "<api-key>")
  .header("x-authorization-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 1.01,\n  \"description\": \"<string>\",\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"currency\": \"MXN\",\n  \"externalPaymentLinkId\": \"<string>\",\n  \"successUrl\": \"<string>\",\n  \"singleUse\": true,\n  \"metadata\": {},\n  \"externalClientId\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"identifierValue\": \"<string>\",\n  \"additionalData\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"amount\": 1.01,\n  \"description\": \"<string>\",\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"currency\": \"MXN\",\n  \"externalPaymentLinkId\": \"<string>\",\n  \"successUrl\": \"<string>\",\n  \"singleUse\": true,\n  \"metadata\": {},\n  \"externalClientId\": \"<string>\",\n  \"productName\": \"<string>\",\n  \"identifierValue\": \"<string>\",\n  \"additionalData\": {}\n}"

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

{
  "data": {
    "paymentLinkId": "<string>",
    "amount": 123,
    "currency": "MXN",
    "description": "<string>",
    "singleUse": true,
    "paymentUrl": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "externalPaymentLinkId": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "successUrl": "<string>",
    "metadata": {},
    "identifierValue": "<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) del PaymentLink. 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

amount

number

requerido

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

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

description

string

requerido

Descripción visible en la página de pago

expiresAt

string<date-time>

requerido

Fecha/hora de expiración (ISO 8601, formato RFC3339). Debe ser en el futuro. Campo obligatorio.

currency

enum<string>

predeterminado:MXN

Código de moneda ISO 4217 (MXN, ARS, PEN, COP, CLP, USD). Default MXN.

Opciones disponibles:

MXN,

ARS,

PEN,

COP,

CLP,

USD

externalPaymentLinkId

string

Llave natural del link. Única por organización. Usada para idempotencia y matching externo.

successUrl

string<uri>

URL de redirección al completar el pago (opcional)

singleUse

boolean

predeterminado:true

Si true, el link se desactiva tras el primer pago. Si false, acepta múltiples pagos (reutilizable). Default true.

metadata

object

Metadatos arbitrarios del cliente (opcional)

externalClientId

string

Identificador del deudor (cliente conocido). Mutuamente excluyente con contactData. Si se proporciona, la Facade resuelve el contacto existente por externalClientId en la organización. El paymentUrl será opaco (no expone identidad si privateLinks=true).

contactData

object

Datos del deudor inline. Mutuamente excluyente con externalClientId. Si se proporciona, se crea un nuevo contacto (o se reutiliza si externalClientId ya existe). El paymentUrl será opaco (no expone identidad si privateLinks=true).

Show child attributes

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.

identifierValue

string

Identificador explícito del link de pago (opcional). Si se proporciona, se sanitiza a URL-safe (alfanumérico + guiones, lowercase, máx 64 chars). Si tras sanear queda vacío, retorna 400 INVALID_REQUEST. Precedencia de resolución: identifierValue explícito > externalClientId (deudor) > sintético. Si se envía identifierValue: se usa ese valor (saneado). Si NO se envía y hay deudor conocido (externalClientId/contactData): se usa el identificador del deudor. Si NO se envía y NO hay deudor: se genera sintético {3letras}-{random}. Exposición en respuesta (PII-safe): SIN deudor conocido (anónimo/reutilizable) se expone identifierValue en respuesta. CON deudor conocido: NO se expone (omitido), incluso si el cliente mandó identifierValue explícito. El paymentUrl usa shortCode opaco si privateLinks=true, o externalClientId si privateLinks=false.

Maximum string length: 64

additionalData

object

Escape hatch para datos adicionales

Respuesta

Link de pago creado

data

object

Show child attributes

requestId

string

Listar links de pago Obtener link de pago

Contacts

Products

Debts

Subscriptions

Payment Links

Crear link de pago

Autorizaciones

Encabezados

Cuerpo

Respuesta