Crear transacción

Crea una única transacción de venta. Para crear varias transacciones a la vez, consulta la página Envío por lotes.

Endpoint

POST https://api.rapidchargeback.com/api/v1/transactions

Autenticación

Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

Campos obligatorios

Campo	Tipo	Descripción
`merchant_id` o `merchant_ref`	string	Informa exactamente uno: `merchant_id` (UUID del merchant en Rapid, debe pertenecer a tu empresa) o `merchant_ref` (ID del vendedor en tu sistema, hasta 100 caracteres, para canales/plataformas con varios vendedores). Si `merchant_ref` es desconocido, el merchant se crea automáticamente con `merchant_name` (opcional, hasta 255 caracteres; se ignora cuando el merchant ya existe). Enviar los dos → `422 VALIDATION_ERROR`. Tus merchants y sus `merchant_id` están en Listar merchants.
`external_id`	string	ID de la transacción en el sistema de origen
`amount`	number	Monto de la transacción (debe ser positivo)
`currency`	string	Código ISO 4217 con 3 letras mayúsculas (ej.: `USD`, `BRL`)
`transaction_date`	string	Fecha de la transacción en formato ISO 8601 (ej.: `2026-04-01T15:30:00Z`)
`card_last4`	string	Últimos 4 dígitos de la tarjeta (exactamente 4 dígitos numéricos)
`items`	array	Al menos 1 ítem (ver los campos del ítem abajo)

Campos del ítem

Obligatorios

Campo	Tipo	Descripción
`product_description`	string	Descripción del producto (hasta 1000 caracteres; por encima de eso la solicitud falla)
`unit_price`	number	Precio unitario

Opcionales

Campo	Tipo	Descripción
`product_name`	string	Nombre del producto
`quantity`	number	Cantidad
`unit_of_measure`	string	Unidad de medida
`category`	string	Categoría del producto

Campos opcionales

Campo	Tipo	Descripción
`external_source`	string	Sistema de origen (por defecto: `custom`)
`order_number`	string	Número de pedido
`transaction_id`	string	ID de la transacción en el gateway de pago. Ver la nota abajo
`arn`	string	Acquirer Reference Number
`banknet_ref`	string	Referencia Banknet (Mastercard)
`auth_code`	string	Código de autorización
`network`	string	Red de la tarjeta: `visa`, `mastercard`, `amex`, `discover`, `other`
`card_bin`	string	BIN de la tarjeta (6 a 8 dígitos numéricos)
`ip_address`	string	Dirección IP del comprador
`clearing_datetime`	string	Fecha de compensación (ISO 8601)
`mcc`	string	Merchant Category Code
`eci`	string	Electronic Commerce Indicator
`pos_entry_mode`	string	Modo de entrada POS
`descriptor`	string	Descriptor de cobro
`correlation_id`	string	ID de correlación
`device_id`	string	ID del dispositivo (mín. 15 caracteres)
`device_fingerprint`	string	Fingerprint del dispositivo (mín. 20 caracteres)
`customer`	object	Datos del comprador (ver abajo)
`addresses`	array	Direcciones de envío y/o de facturación (ver abajo)
`payments`	array	Datos de pago (ver abajo)
`refunds`	array	Datos de reembolso (ver abajo)

Límites de tamaño

Todo campo de texto tiene un tope. Por encima de él la respuesta es 422 VALIDATION_ERROR señalando el campo, nunca un error de servidor.

Límite	Campos
1000	`product_description`
255	`descriptor`, `merchant_name`, `product_name`, `device_fingerprint`, `street`, `reason` (refund)
200	`billing_name`
100	`external_id`, `order_number`, `transaction_id`, `arn`, `banknet_ref`, `correlation_id`, `merchant_ref`, `device_id`, `first_name`, `last_name`, `city`, `state`, `category`
64	`method_masked`, `reference_number`
45	`ip_address` (cabe IPv6)
50	`external_source`, `auth_code`, `account_id`
32	`unit_of_measure`
30	`phone`, `postal_code`, `wallet_indicator`
20	`number` (dirección)
16	`payment_type`
10	`mcc`, `pos_entry_mode`
7	`card_expiry`
5	`eci`
2	`cvv2_presence_indicator`, `avs_result`

email sigue el límite de 255 y necesita un formato válido. currency, card_bin, card_last4, country y network tienen formato fijo, descrito en la tabla de campos.

Nota sobre `transaction_id`

Es opcional, pero complétalo siempre que el cobro haya pasado por un gateway de pago: es por este campo que Rapid vincula un contracargo futuro a la transacción. Envía el identificador del cobro en el gateway, no tu número de pedido (ese es el order_number).

Si usas un gateway cuyas disputas llegan a Rapid y el campo viene vacío, el contracargo igual se recibe, pero sin transacción asociada: sin historial, sin evidencia adjunta y sin los datos de autenticación, que son justamente el material de la defensa. Alternativa equivalente: enviar external_source con el nombre del gateway y external_id con el id del cobro.

Objeto `customer` (todos opcionales)

Campo	Tipo	Descripción
`first_name`	string	Nombre
`last_name`	string	Apellido
`email`	string	Correo electrónico (formato válido)
`billing_name`	string	Nombre en la tarjeta
`account_id`	string	ID de la cuenta del comprador en tu sistema
`phone`	string	Teléfono

Objeto `address` (dentro del array `addresses`)

Campo	Tipo	Obligatorio	Descripción
`type`	string	Sí	`shipping` o `billing`
`street`	string	No	Calle
`number`	string	No	Número
`city`	string	No	Ciudad
`state`	string	No	Estado/Región
`postal_code`	string	No	Código postal
`country`	string	No	Código de país ISO 3166-1, 2 o 3 letras mayúsculas (`BR`/`BRA`, `US`/`USA`). Se recomienda alpha-3.

Campos de autenticación del pago (raíz, todos opcionales)

Insumos de la protección contra fraude y de 3-DS. Cuanto más completes, más fuerte la deflexión y la defensa.

Campo	Tipo	Descripción
`cvv2_presence_indicator`	string	Indicador de presencia del CVV2 en la autorización
`cvv2_result`	string	Resultado de la verificación del CVV2: `M`, `N`, `P`, `S`, `U` o `Y`, tal como vino en la respuesta de la autorización
`avs_result`	string	Resultado del AVS (verificación de dirección)
`cardholder_verification_approved`	boolean	3-DS/verificación del titular aprobada
`authentication_response_type`	string	Tipo de respuesta de la autenticación 3-DS: `attempt` (intento) o `confirm` (autenticación confirmada)
`wallet_indicator`	string	Billetera digital usada (ej.: Apple Pay, Google Pay)

Cuenta del comprador (dentro de `customer`, todos opcionales)

Indican si la compra la hizo una cuenta conocida, y desde cuándo existe. Son el material más fuerte de la defensa en una disputa por fraude: un comprador con una cuenta antigua y con sesión iniciada es difícil de disputar como “no lo reconozco”.

Campo	Tipo	Descripción
`registered_at`	string (ISO 8601)	Cuándo se creó la cuenta del comprador en tu sistema
`registered_at_source`	string	De dónde viene `registered_at`: `merchant_api` (registro de la cuenta en tu sistema) o `client_declared` (declaración tuya, sin ese registro)
`account_authenticated`	boolean	El comprador tenía la sesión iniciada en la cuenta al comprar
`account_authenticated_source`	string	Cómo lo sabes: `per_account` (verificado en esta compra) o `onboarding_flag` (regla de tu tienda, por ejemplo, toda compra exige login)
`account_authenticated_at`	string (ISO 8601)	Cuándo fue el login
`auth_method`	string	Cómo entró el comprador: `password`, `otp`, `2fa`, `biometric`, `oauth` u `other`
`account_source_method`	string	De dónde vienen los datos de la cuenta: `merchant_api` o `client_declared`
`checkout_type`	string	Cómo se hizo la compra: `guest` (sin cuenta), `authenticated` (cuenta existente, con sesión iniciada) o `registered_at_checkout` (cuenta creada durante la compra)

Un valor fuera de las listas responde 422 VALIDATION_ERROR.

Objeto `payment` (todos opcionales)

Campo	Tipo	Descripción
`payment_type`	string	Tipo de pago (credit, debit, pix, etc.)
`method_masked`	string	Número enmascarado
`matched_payment`	boolean	Si este pago fue el utilizado (por defecto: true)
`card_bin`	string	BIN (6-8 dígitos)
`card_last4`	string	Últimos 4 dígitos (4 dígitos numéricos)
`installments`	integer	Número de cuotas
`card_expiry`	string	Vencimiento (MM/YYYY)

Objeto `refund`

Campo	Tipo	Obligatorio	Descripción
`amount`	number	Sí	Monto del reembolso (positivo)
`currency`	string	Sí	Moneda (3 letras mayúsculas, ISO 4217)
`reference_number`	string	No	Identificador del reembolso
`reason`	string	No	Motivo del reembolso
`refund_datetime`	string	No	Fecha del reembolso (ISO 8601)

Validaciones

transaction_date debe estar en ISO 8601 con zona horaria
currency debe ser un código ISO 4217 (3 letras mayúsculas)
amount debe ser mayor que cero
card_last4 debe tener exactamente 4 dígitos numéricos
card_bin debe tener de 6 a 8 dígitos numéricos
device_id debe tener como mínimo 15 caracteres
device_fingerprint debe tener como mínimo 20 caracteres
La combinación external_source + external_id no puede duplicar una transacción existente de tu empresa

Warnings

La API devuelve avisos (sin bloquear la creación) cuando faltan campos opcionales importantes:

Cuándo	Aviso
Sin `card_bin`	`card_bin missing: reduces match accuracy`
Sin `order_number`	`order_number missing: recommended to identify the order in dispute responses`
Sin `ip_address`, `device_id` y `device_fingerprint`	`ip_address, device_id and device_fingerprint missing: recommended, fraud protection relies on them`

Basta uno de los tres identificadores para que desaparezca el último aviso: la IP no es obligatoria. Y a propósito no hay aviso de dirección: quien vende bienes digitales no debe enviar dirección de envío (ver protección contra fraude).

La clave warnings solo aparece en la respuesta cuando hay al menos un aviso. No cuentes con warnings: [].

Ejemplo de solicitud

Las credenciales vienen de variables de entorno (RAPID_CLIENT_ID y RAPID_CLIENT_SECRET), nunca escritas en el código.

curl -X POST https://api.rapidchargeback.com/api/v1/transactions \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "external_source": "shopify",
    "external_id": "TXN-2026-001",
    "transaction_date": "2026-04-01T15:30:00Z",
    "amount": 150.00,
    "currency": "USD",
    "card_last4": "4242",
    "card_bin": "424242",
    "order_number": "ORD-001",
    "auth_code": "AUTH999",
    "network": "visa",
    "descriptor": "LOJA EXEMPLO",
    "ip_address": "203.0.113.10",
    "items": [
      {
        "product_description": "Assinatura Premium - Mensal",
        "product_name": "Plano Premium",
        "quantity": 1,
        "unit_price": 150.00
      }
    ],
    "customer": {
      "first_name": "João",
      "last_name": "Silva",
      "email": "joao@exemplo.com"
    },
    "addresses": [
      {
        "type": "shipping",
        "street": "Rua das Flores",
        "number": "123",
        "city": "São Paulo",
        "state": "SP",
        "postal_code": "01001000",
        "country": "BRA"
      }
    ]
  }'

const credenciales = Buffer.from(`${process.env.RAPID_CLIENT_ID}:${process.env.RAPID_CLIENT_SECRET}`).toString('base64')

const respuesta = await fetch('https://api.rapidchargeback.com/api/v1/transactions', {
  method: 'POST',
  headers: { Authorization: `Basic ${credenciales}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    merchant_id: '00000000-0000-0000-0000-000000000001',
    external_source: 'shopify',
    external_id: 'TXN-2026-001',
    transaction_date: '2026-04-01T15:30:00Z',
    amount: 150.0,
    currency: 'USD',
    card_last4: '4242',
    card_bin: '424242',
    order_number: 'ORD-001',
    auth_code: 'AUTH999',
    network: 'visa',
    descriptor: 'LOJA EXEMPLO',
    ip_address: '203.0.113.10',
    items: [
      {
        product_description: 'Assinatura Premium - Mensal',
        product_name: 'Plano Premium',
        quantity: 1,
        unit_price: 150.0,
      },
    ],
    customer: {
      first_name: 'João',
      last_name: 'Silva',
      email: 'joao@exemplo.com',
    },
    addresses: [
      {
        type: 'shipping',
        street: 'Rua das Flores',
        number: '123',
        city: 'São Paulo',
        state: 'SP',
        postal_code: '01001000',
        country: 'BRA',
      },
    ],
  }),
})

const cuerpo = await respuesta.json()
if (!respuesta.ok) throw new Error(`${respuesta.status} ${cuerpo.error.code}: ${cuerpo.error.message}`)

console.log('Transacción creada:', cuerpo.data.id)
for (const aviso of cuerpo.warnings ?? []) console.warn('Aviso:', aviso)

import os

import requests

respuesta = requests.post(
    "https://api.rapidchargeback.com/api/v1/transactions",
    auth=(os.environ["RAPID_CLIENT_ID"], os.environ["RAPID_CLIENT_SECRET"]),
    json={
        "merchant_id": "00000000-0000-0000-0000-000000000001",
        "external_source": "shopify",
        "external_id": "TXN-2026-001",
        "transaction_date": "2026-04-01T15:30:00Z",
        "amount": 150.00,
        "currency": "USD",
        "card_last4": "4242",
        "card_bin": "424242",
        "order_number": "ORD-001",
        "auth_code": "AUTH999",
        "network": "visa",
        "descriptor": "LOJA EXEMPLO",
        "ip_address": "203.0.113.10",
        "items": [
            {
                "product_description": "Assinatura Premium - Mensal",
                "product_name": "Plano Premium",
                "quantity": 1,
                "unit_price": 150.00,
            }
        ],
        "customer": {
            "first_name": "João",
            "last_name": "Silva",
            "email": "joao@exemplo.com",
        },
        "addresses": [
            {
                "type": "shipping",
                "street": "Rua das Flores",
                "number": "123",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "01001000",
                "country": "BRA",
            }
        ],
    },
    timeout=30,
)

cuerpo = respuesta.json()
if not respuesta.ok:
    raise RuntimeError(f"{respuesta.status_code} {cuerpo['error']['code']}: {cuerpo['error']['message']}")

print("Transacción creada:", cuerpo["data"]["id"])
for aviso in cuerpo.get("warnings", []):
    print("Aviso:", aviso)

<?php
$transaccion = [
    'merchant_id' => '00000000-0000-0000-0000-000000000001',
    'external_source' => 'shopify',
    'external_id' => 'TXN-2026-001',
    'transaction_date' => '2026-04-01T15:30:00Z',
    'amount' => 150.00,
    'currency' => 'USD',
    'card_last4' => '4242',
    'card_bin' => '424242',
    'order_number' => 'ORD-001',
    'auth_code' => 'AUTH999',
    'network' => 'visa',
    'descriptor' => 'LOJA EXEMPLO',
    'ip_address' => '203.0.113.10',
    'items' => [
        [
            'product_description' => 'Assinatura Premium - Mensal',
            'product_name' => 'Plano Premium',
            'quantity' => 1,
            'unit_price' => 150.00,
        ],
    ],
    'customer' => [
        'first_name' => 'João',
        'last_name' => 'Silva',
        'email' => 'joao@exemplo.com',
    ],
    'addresses' => [
        [
            'type' => 'shipping',
            'street' => 'Rua das Flores',
            'number' => '123',
            'city' => 'São Paulo',
            'state' => 'SP',
            'postal_code' => '01001000',
            'country' => 'BRA',
        ],
    ],
];

$ch = curl_init('https://api.rapidchargeback.com/api/v1/transactions');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_USERPWD => getenv('RAPID_CLIENT_ID') . ':' . getenv('RAPID_CLIENT_SECRET'),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($transaccion),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);

$crudo = curl_exec($ch);
if ($crudo === false) {
    throw new RuntimeException('Error de red: ' . curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$cuerpo = json_decode($crudo, true);

if ($status >= 400) {
    throw new RuntimeException("$status {$cuerpo['error']['code']}: {$cuerpo['error']['message']}");
}

echo 'Transacción creada: ', $cuerpo['data']['id'], PHP_EOL;
foreach ($cuerpo['warnings'] ?? [] as $aviso) {
    echo 'Aviso: ', $aviso, PHP_EOL;
}

Ejemplos de respuesta

Éxito

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000042",
    "company_id": "...",
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "external_id": "TXN-2026-001",
    "amount": 150.00,
    "currency": "USD",
    "transaction_date": "2026-04-01T15:30:00.000Z",
    "card_last4": "4242",
    "created_at": "2026-04-01T15:31:00.000Z",
    "transaction_items": [...],
    "transaction_customers": [...],
    "transaction_addresses": [...]
  }
}

Duplicado

{
  "error": {
    "code": "TRANSACTION_DUPLICATE",
    "message": "Transaction already exists"
  }
}

Error de validación

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "card_last4 must be exactly 4 digits"
  }
}