# Crear Pagos Combinados con Tarjeta
Esta guía explica cómo procesar transacciones de pago combinadas utilizando múltiples métodos de pago en una sola compra. Los pagos combinados permiten a los clientes dividir el importe total en varias tarjetas, ya sean de crédito o débito, proporcionando una mayor flexibilidad para compras más grandes.
## Requisitos
Antes de seguir los pasos, necesita:
* Crear su cuenta poniéndose en contacto con el equipo de Soporte de Integración para obtener sus credenciales de la API `client_id` y `client_secret`.
* Generar su token con sus credenciales utilizando el [endpoint de Authentication](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/authentication).
> Getnet proporciona una [Postman Collection](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-postman-collection) para ayudarle a replicar estos casos de uso localmente. También puede probar la API en el entorno sandbox utilizando la API Reference disponible en la documentación.
## Especificidades de los Casos de Uso
Al integrar cualquier solución de Getnet, se aplican requisitos específicos del mercado. Asegúrese de revisar los recursos a continuación antes de pasar a producción:
* [Códigos de divisa](https://www.google.com/search?q=/en/articles%3Farticle%3Dcurrency-codes)
* [Tipos de documento](https://www.google.com/search?q=/en/articles%3Farticle%3Ddocument-types)
* [Impuestos y regulaciones locales](https://www.google.com/search?q=/en/articles%3Farticle%3Dtaxes-and-regulations)
También puede utilizar [tarjetas de prueba](https://www.google.com/search?q=/en/articles%3Farticle%3Dtest-cards) para simular escenarios específicos. Puede encontrar más información sobre los requisitos específicos para cada país en la sección de [Developer Resources](https://www.google.com/search?q=/en/articles%3Farticle%3Dcurrency-codes) de la documentación de Getnet.
## Disponibilidad de la plataforma
Los pagos combinados son soportados en múltiples mercados. Para obtener una referencia completa de los métodos de pago disponibles en cada país, consulte la [Disponibilidad de Pagos Combinados](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dreference-combined-payments-and-availability).
## Proceso de Pago Combinado
Esta sección le orienta en la creación de una transacción de pago combinado donde un cliente puede utilizar múltiples tarjetas para completar una sola compra. El proceso implica autorizar múltiples métodos de pago de forma simultánea y, opcionalmente, su captura posterior.
El siguiente diagrama ilustra el flujo completo del pago combinado, mostrando cómo se tokenizan y autorizan múltiples tarjetas en una sola petición:
### Tokenizar los Datos de la Tarjeta (Opcional)
En lugar de enviar los números de tarjeta originales (raw) en su petición de pago, puede utilizar la tokenización para mejorar la seguridad y reducir el alcance del cumplimiento del PCI DSS. Para utilizar tarjetas tokenizadas:
1. Tokenice cada tarjeta llamando al [endpoint de Card Tokenization](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/cards/post/dpm/cofre-gw-proxy/v1/tokens/card) con el `card_number` y el `customer_id`.
2. En su petición de pago, reemplace el campo `card.number` por `card.number_token` utilizando el valor del token recibido del endpoint de tokenización para cada método de pago.
Si envía `card.number_token`, no necesita incluir la propiedad `card.number` en la petición. Puede utilizar el número de la tarjeta original (raw) o la versión tokenizada, pero no ambos. Para obtener todos los detalles sobre la tokenización, consulte la documentación de [Tokenización y Vault](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-tokenization-and-vault).
### Paso 1: Autorizar el Pago Combinado
Un pago combinado comienza creando múltiples autorizaciones de pago en una sola petición. Utilice el [endpoint de Combined Payments - Authorize](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/combined-payments/post/dpm/payments-gwproxy/v2/payments/combined) para procesar múltiples métodos de pago simultáneamente.
La estructura del pago combinado le permite especificar un array de métodos de pago, cada uno con sus propios detalles de tarjeta e importe. La suma de todos los importes de pago individuales debe ser igual al importe total del pedido.
La siguiente tabla enumera los campos mínimos que necesita enviar:
| Atributo | Descripción | Requerido |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `idempotency_key` | Identificador único para evitar cargos duplicados. | Sí |
| `order_id` | ID de referencia del comercio utilizado para la conciliación. | Sí |
| `request_id` | Identificador de rastreo para auditorías de idempotencia y seguimiento de soporte. | Recomendado |
| `data.amount` | Importe total de la transacción en céntimos (debe ser igual a la suma de todos los pagos).| Sí |
| `data.currency` | Código de la divisa ISO utilizado en la transacción. | Sí |
| `data.customer` | Detalles del cliente (nombre, correo electrónico, teléfono, documento, dirección de facturación completa). **Obligatorio en producción para evitar bloqueos del antifraude.** | Sí (Prod) |
| `data.payments[]` | Array de objetos de pago, cada uno de los cuales contiene los detalles del método de pago.| Sí |
| `data.payments[].payment_method` | Debe ser `CREDIT` o `DEBIT` para cada pago. | Sí |
| `data.payments[].transaction_type` | Define cómo se procesa la transacción (`FULL`, `INSTALL_NO_INTEREST`, `INSTALL_WITH_INTEREST`). | Sí |
| `data.payments[].number_installments` | Número de plazos (utilice `1` para un solo pago). | Sí |
| `data.payments[].amount` | Importe para este método de pago específico en céntimos. | Sí |
| `data.payments[].card` | Conjunto de datos de la tarjeta (`number`, `brand`, `expiration_month`, `expiration_year`, `security_code`, `cardholder_name`). | Sí |
| `data.additional_data.device` | Información de fingerprint del dispositivo (`ip_address`, `device_id`, `finger_print`) para análisis de antifraude. | Sí (Prod) |
Los objetos necesarios para la validación del antifraude deben incluir los siguientes campos:
| Objeto / Campo | Descripción |
| -------------------------------------- | -------------------------------------------------- |
| `customer.first_name` | Nombre del cliente |
| `customer.last_name` | Apellido del cliente |
| `customer.email` | Dirección de correo electrónico del cliente |
| `customer.phone_number` | Número de teléfono (formato internacional) |
| `customer.document_type` | Tipo de documento (ej., CPF, DNI, etc.) |
| `customer.document_number` | Número de documento (sin puntuación) |
| `customer.billing_address.street` | Nombre de la calle |
| `customer.billing_address.number` | Número de la dirección |
| `customer.billing_address.district` | Distrito o barrio |
| `customer.billing_address.city` | Ciudad |
| `customer.billing_address.state` | Estado o provincia |
| `customer.billing_address.country` | Código del país (ISO) |
| `customer.billing_address.postal_code` | Código postal |
| `additional_data.device.ip_address` | Dirección IP del cliente |
| `additional_data.device.device_id` | ID de la sesión del fingerprint del dispositivo (UUIDv4) |
| `additional_data.device.finger_print` | Hash del fingerprint generado por el script de antifraude |
> Los datos de antifraude son **obligatorios** para entornos de producción. Las transacciones que carezcan del fingerprint del dispositivo o de la información del cliente serán bloqueadas automáticamente por los equipos de antifraude para prevenir el fraude. Consulte la documentación de [Antifraude](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Drisk-security-antifraud) para obtener detalles completos sobre la implementación.
Al final de una autorización exitosa, recibirá un `payment_id`, que se utiliza para identificar esta transacción.
El siguiente bloque de código muestra un ejemplo de una petición de pago combinado utilizando dos tarjetas diferentes:
```bash
curl --request POST \
--url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments/combined \
--header 'authorization: Bearer ' \
--header 'content-type: application/json' \
--header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
--header 'x-transaction-channel-entry: XX' \
--data '{
"idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
"request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
"order_id": "ORDER-10187383",
"data": {
"amount": 200000,
"currency": "BRL",
"customer_id": "test",
"customer": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"document_type": "CPF",
"document_number": "12345678900",
"phone_number": "+5511999999999",
"billing_address": {
"street": "Av. Paulista",
"number": "1000",
"complement": "Apto 101",
"district": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"postal_code": "01310-100"
}
},
"payments": [
{
"payment_method": "CREDIT",
"save_card_data": false,
"transaction_type": "FULL",
"number_installments": 1,
"amount": 120000,
"soft_descriptor": "LOJA*TESTE*COMPRA-123",
"card": {
"number": "5155901222260000",
"expiration_month": "09",
"expiration_year": "30",
"cardholder_name": "Card Holder One",
"security_code": "517"
}
},
{
"payment_method": "CREDIT",
"save_card_data": false,
"transaction_type": "FULL",
"number_installments": 1,
"amount": 80000,
"soft_descriptor": "LOJA*TESTE*COMPRA-123",
"card": {
"number": "4012001037141112",
"expiration_month": "12",
"expiration_year": "30",
"cardholder_name": "Card Holder Two",
"security_code": "123"
}
}
],
"additional_data": {
"device": {
"ip_address": "192.168.1.1",
"device_id": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
"finger_print": "1a2b3c4d5e6f7g8h9i0j"
}
}
}
}'
```
Ejemplo de respuesta con todos los pagos `APPROVED`:
```json
{
"idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
"seller_id": "e0ed6f00-fdc5-46d6-9557-6a2cac641b09",
"payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
"order_id": "ORDER-10187383",
"amount": 200000,
"currency": "BRL",
"status": "APPROVED",
"received_at": "2025-10-31T13:40:47.382Z",
"payments": [
{
"payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75-1",
"amount": 120000,
"status": "APPROVED",
"payment_method": "CREDIT",
"transaction_id": "MCC50205G1020",
"authorized_at": "2025-10-31T13:40:47.382Z",
"reason_code": "00",
"reason_message": "captured",
"brand": "MASTERCARD",
"authorization_code": "204050"
},
{
"payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75-2",
"amount": 80000,
"status": "APPROVED",
"payment_method": "CREDIT",
"transaction_id": "MCC50205G1021",
"authorized_at": "2025-10-31T13:40:47.582Z",
"reason_code": "00",
"reason_message": "captured",
"brand": "VISA",
"authorization_code": "204051"
}
]
}
```
### Paso 2: Comprobar el Estado del Pago (Opcional)
La respuesta de autorización del pago combinado mostrará el estado general y el estado individual para cada método de pago.
Debido a que algunos pagos se procesan de forma asíncrona, el estado puede cambiar con el tiempo. Para obtener el estado más reciente de una transacción, utilice el [endpoint de Get Transaction](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payment-record-management/get/dpm/hub-payment-info/v1/payments/info/%7Bpayment_id%7D).
Para obtener actualizaciones en tiempo real sin necesidad de hacer polling, se recomienda utilizar Webhooks para recibir notificaciones sobre cada cambio de estado.
### Próximos Pasos
Ahora que ha creado con éxito un pago combinado, puede explorar más funciones de la Global API de Getnet:
* Aprenda cómo crear [Pagos a Plazos (Installments)](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dcreate-payments-with-installments).
* Lea acerca de los [Pagos con 3DS](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-3ds-authentication-20).
* Explore la [Tokenización y Vault](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-tokenization-and-vault) para almacenar de forma segura los datos de la tarjeta.