Crear orden de pago
curl --request POST \
--url https://tapipay-facade.homo.tapila.cloud/v2/debts/orders \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-authorization-token: <api-key>' \
--data '
{
"externalRequestId": "<string>",
"externalClientId": "<string>",
"amount": 1.01,
"paymentMethodType": "BANK_ACCOUNT",
"externalPaymentMethodId": "b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8",
"dueDate": "2023-12-25",
"description": "<string>",
"additionalData": {
"source": "crm",
"folio": "F-2026-0042"
},
"companyCode": "<string>"
}
'import requests
url = "https://tapipay-facade.homo.tapila.cloud/v2/debts/orders"
payload = {
"externalRequestId": "<string>",
"externalClientId": "<string>",
"amount": 1.01,
"paymentMethodType": "BANK_ACCOUNT",
"externalPaymentMethodId": "b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8",
"dueDate": "2023-12-25",
"description": "<string>",
"additionalData": {
"source": "crm",
"folio": "F-2026-0042"
},
"companyCode": "<string>"
}
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({
externalRequestId: '<string>',
externalClientId: '<string>',
amount: 1.01,
paymentMethodType: 'BANK_ACCOUNT',
externalPaymentMethodId: 'b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8',
dueDate: '2023-12-25',
description: '<string>',
additionalData: {source: 'crm', folio: 'F-2026-0042'},
companyCode: '<string>'
})
};
fetch('https://tapipay-facade.homo.tapila.cloud/v2/debts/orders', 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.homo.tapila.cloud/v2/debts/orders",
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([
'externalRequestId' => '<string>',
'externalClientId' => '<string>',
'amount' => 1.01,
'paymentMethodType' => 'BANK_ACCOUNT',
'externalPaymentMethodId' => 'b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8',
'dueDate' => '2023-12-25',
'description' => '<string>',
'additionalData' => [
'source' => 'crm',
'folio' => 'F-2026-0042'
],
'companyCode' => '<string>'
]),
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.homo.tapila.cloud/v2/debts/orders"
payload := strings.NewReader("{\n \"externalRequestId\": \"<string>\",\n \"externalClientId\": \"<string>\",\n \"amount\": 1.01,\n \"paymentMethodType\": \"BANK_ACCOUNT\",\n \"externalPaymentMethodId\": \"b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8\",\n \"dueDate\": \"2023-12-25\",\n \"description\": \"<string>\",\n \"additionalData\": {\n \"source\": \"crm\",\n \"folio\": \"F-2026-0042\"\n },\n \"companyCode\": \"<string>\"\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.homo.tapila.cloud/v2/debts/orders")
.header("x-api-key", "<api-key>")
.header("x-authorization-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"externalRequestId\": \"<string>\",\n \"externalClientId\": \"<string>\",\n \"amount\": 1.01,\n \"paymentMethodType\": \"BANK_ACCOUNT\",\n \"externalPaymentMethodId\": \"b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8\",\n \"dueDate\": \"2023-12-25\",\n \"description\": \"<string>\",\n \"additionalData\": {\n \"source\": \"crm\",\n \"folio\": \"F-2026-0042\"\n },\n \"companyCode\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://tapipay-facade.homo.tapila.cloud/v2/debts/orders")
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 \"externalRequestId\": \"<string>\",\n \"externalClientId\": \"<string>\",\n \"amount\": 1.01,\n \"paymentMethodType\": \"BANK_ACCOUNT\",\n \"externalPaymentMethodId\": \"b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8\",\n \"dueDate\": \"2023-12-25\",\n \"description\": \"<string>\",\n \"additionalData\": {\n \"source\": \"crm\",\n \"folio\": \"F-2026-0042\"\n },\n \"companyCode\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"debt": {
"debtId": "debt_CARGO-2026-00042",
"externalRequestId": "<string>",
"status": "PENDING",
"amount": 123,
"amountPaid": 123,
"currency": "MXN",
"dueDate": "2023-12-25",
"createdAt": "2023-11-07T05:31:56Z",
"allowOverduePayment": true,
"contact": {
"contactId": "con_cmruu1lx2000002l4ctm7b0et",
"externalClientId": "<string>",
"createdInline": true
}
},
"order": {
"orderId": "6f1c2b9e-4d3a-4b8e-9a71-2c5d8e0f1a23",
"status": "PROCESSING",
"amount": 123,
"currency": "MXN",
"paymentMethod": {
"externalPaymentMethodId": "<string>",
"paymentMethodType": "BANK_ACCOUNT"
},
"estimatedProcessingDate": "2023-12-25"
}
},
"requestId": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}{
"message": "Unauthorized"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}Payment orders
Crear orden de pago
Registra una deuda y pide en el mismo request el cargo a la cuenta bancaria que el usuario registró en el enrolamiento. No requiere que el usuario esté adherido a un producto. El cargo es asíncrono: la orden nace en PROCESSING; consulta el resultado con GET /v2/debts/orders. La idempotencia es por externalRequestId en el body: un reintento con la misma llave, el mismo externalClientId, el mismo amount y el mismo externalPaymentMethodId retoma la deuda si sigue PENDING; si la llave ya se usó con otros datos (incluido otro externalPaymentMethodId, o enviarlo en un intento y no en el otro) o ya tiene una orden, 409.
POST
/
v2
/
debts
/
orders
Crear orden de pago
curl --request POST \
--url https://tapipay-facade.homo.tapila.cloud/v2/debts/orders \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-authorization-token: <api-key>' \
--data '
{
"externalRequestId": "<string>",
"externalClientId": "<string>",
"amount": 1.01,
"paymentMethodType": "BANK_ACCOUNT",
"externalPaymentMethodId": "b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8",
"dueDate": "2023-12-25",
"description": "<string>",
"additionalData": {
"source": "crm",
"folio": "F-2026-0042"
},
"companyCode": "<string>"
}
'import requests
url = "https://tapipay-facade.homo.tapila.cloud/v2/debts/orders"
payload = {
"externalRequestId": "<string>",
"externalClientId": "<string>",
"amount": 1.01,
"paymentMethodType": "BANK_ACCOUNT",
"externalPaymentMethodId": "b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8",
"dueDate": "2023-12-25",
"description": "<string>",
"additionalData": {
"source": "crm",
"folio": "F-2026-0042"
},
"companyCode": "<string>"
}
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({
externalRequestId: '<string>',
externalClientId: '<string>',
amount: 1.01,
paymentMethodType: 'BANK_ACCOUNT',
externalPaymentMethodId: 'b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8',
dueDate: '2023-12-25',
description: '<string>',
additionalData: {source: 'crm', folio: 'F-2026-0042'},
companyCode: '<string>'
})
};
fetch('https://tapipay-facade.homo.tapila.cloud/v2/debts/orders', 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.homo.tapila.cloud/v2/debts/orders",
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([
'externalRequestId' => '<string>',
'externalClientId' => '<string>',
'amount' => 1.01,
'paymentMethodType' => 'BANK_ACCOUNT',
'externalPaymentMethodId' => 'b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8',
'dueDate' => '2023-12-25',
'description' => '<string>',
'additionalData' => [
'source' => 'crm',
'folio' => 'F-2026-0042'
],
'companyCode' => '<string>'
]),
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.homo.tapila.cloud/v2/debts/orders"
payload := strings.NewReader("{\n \"externalRequestId\": \"<string>\",\n \"externalClientId\": \"<string>\",\n \"amount\": 1.01,\n \"paymentMethodType\": \"BANK_ACCOUNT\",\n \"externalPaymentMethodId\": \"b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8\",\n \"dueDate\": \"2023-12-25\",\n \"description\": \"<string>\",\n \"additionalData\": {\n \"source\": \"crm\",\n \"folio\": \"F-2026-0042\"\n },\n \"companyCode\": \"<string>\"\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.homo.tapila.cloud/v2/debts/orders")
.header("x-api-key", "<api-key>")
.header("x-authorization-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"externalRequestId\": \"<string>\",\n \"externalClientId\": \"<string>\",\n \"amount\": 1.01,\n \"paymentMethodType\": \"BANK_ACCOUNT\",\n \"externalPaymentMethodId\": \"b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8\",\n \"dueDate\": \"2023-12-25\",\n \"description\": \"<string>\",\n \"additionalData\": {\n \"source\": \"crm\",\n \"folio\": \"F-2026-0042\"\n },\n \"companyCode\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://tapipay-facade.homo.tapila.cloud/v2/debts/orders")
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 \"externalRequestId\": \"<string>\",\n \"externalClientId\": \"<string>\",\n \"amount\": 1.01,\n \"paymentMethodType\": \"BANK_ACCOUNT\",\n \"externalPaymentMethodId\": \"b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8\",\n \"dueDate\": \"2023-12-25\",\n \"description\": \"<string>\",\n \"additionalData\": {\n \"source\": \"crm\",\n \"folio\": \"F-2026-0042\"\n },\n \"companyCode\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"debt": {
"debtId": "debt_CARGO-2026-00042",
"externalRequestId": "<string>",
"status": "PENDING",
"amount": 123,
"amountPaid": 123,
"currency": "MXN",
"dueDate": "2023-12-25",
"createdAt": "2023-11-07T05:31:56Z",
"allowOverduePayment": true,
"contact": {
"contactId": "con_cmruu1lx2000002l4ctm7b0et",
"externalClientId": "<string>",
"createdInline": true
}
},
"order": {
"orderId": "6f1c2b9e-4d3a-4b8e-9a71-2c5d8e0f1a23",
"status": "PROCESSING",
"amount": 123,
"currency": "MXN",
"paymentMethod": {
"externalPaymentMethodId": "<string>",
"paymentMethodType": "BANK_ACCOUNT"
},
"estimatedProcessingDate": "2023-12-25"
}
},
"requestId": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}{
"message": "Unauthorized"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>",
"index": 123,
"externalRequestId": "<string>"
}
]
},
"requestId": "<string>"
}Autorizaciones
API key del API Gateway de Tapi. Requerida en todas las operaciones. Distinta por ambiente (desarrollo, homologación, producción).
Token TAPI JWT. Requerido en todas las operaciones. Se envía sin prefijo "Bearer". Ej: x-authorization-token: eyJhbGci...
Cuerpo
application/json
Registra una deuda y pide en el mismo request el cargo a la cuenta bancaria que el usuario registró. Solo acepta estos campos: cualquier otro devuelve 400 INVALID_REQUEST. La deuda no admite pagos parciales.
Llave de idempotencia de la orden. El debtId resultante es debt_. Ante un 500, reintenta con el mismo valor.
Required string length:
1 - 250Identificador de un contacto existente. Si no existe, 404 CONTACT_NOT_FOUND.
Minimum string length:
1Monto en pesos, hasta 2 decimales.
Rango requerido:
x >= 0.01Medio con el que se cobra. Por ahora solo la cuenta bancaria registrada.
Opciones disponibles:
BANK_ACCOUNT Cuenta con la que se cobra, tal como la devuelve GET /payment-methods. Tiene que ser una cuenta vigente del usuario y del tipo de paymentMethodType; si no, 422 PAYMENT_METHOD_NOT_AVAILABLE. Si no se envía, se cobra con la cuenta predeterminada del usuario.
Minimum string length:
1Ejemplo:
"b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8"
Vencimiento de la deuda (YYYY-MM-DD). Si no se envía, la fecha de hoy en America/Mexico_City más 7 días.
Required string length:
1 - 255Datos adicionales propios del cliente. Debe ser un objeto plano; un escalar (string, número o booleano) devuelve 400 INVALID_REQUEST. No puede usar claves reservadas, que TapiPay escribe internamente: description, paymentMethods, productName, externalProductId, debtExpirationDate, overduePayment, allowPartialPayments, recurringDebt. Si aparece alguna, la API responde 400 INVALID_REQUEST con details[].field = additionalData. Se persiste en la deuda (en ligas de pago, en la deuda asociada al link; en suscripciones, en las deudas generadas).
Ejemplo:
{ "source": "crm", "folio": "F-2026-0042" }
Solo si tu cliente tiene varias companies.