Crear una compra

Aprenda a crear una compra utilizando nuestra API. Este proceso es apto tanto para comercios con certificación PCI como para aquellos que no la tienen.

Configuración de la autenticación

Todos los métodos de la API de Compras requieren los siguientes encabezados de autenticación:

Llave	Valor	Comentarios
`Content-Type`	`application/json`	Indica que la solicitud se enviará en formato JSON.
`Authorization`	`Basic {{Clave Privada del Comercio}}`	Incluya la palabra `Basic` seguida de su `{{Clave Privada del Comercio}}` (y el identificador como comercio). Ejemplo: `Basic RVkeLr-86_iTzSMLvDtuyQ-1zqIcsmFG-oSzncn_uFv-nj7bhB3rtZg__`

Configurar el idioma de los códigos de respuesta

Es posible recibir la descripción de errores en un idioma preferido. Para esto, envíe el encabezado lang, utilizando uno de los siguientes códigos en formato ISO 639-1:

Code	Language
`en`	English. Si no envía este encabezado o especifica un idioma no existente, recibirá los errores en inglés por defecto.
`es`	Español.
`pt`	Portugués.

Crear una compra

Esta sección explica detalladamente cómo generar una Compra para comercios sin certificación PCI DSS, permitiendo procesar pagos sin manejar directamente datos sensibles de tarjetas.

Una vez que haya tokenizado una tarjeta, es posible generar una compra usando este endpoint.

Para medios de pago alternativos, como pagos en efectivo o transferencias bancarias, es necesario enviar el ID del medio de pago correspondiente para iniciar la transacción.

Versiones anteriores de la API

La documentación de la API versión V1 y V2 está disponible en la sección de Legacy

URL de la solicitud

Es necesario realizar una petición POST a las siguientes URLs según sus necesidades:

Producción: https://api.bamboopayment.com/v3/api/purchase
Pruebas: https://api.stage.bamboopayment.com/v3/api/purchase

Parámetros de la solicitud

Parámetro	Tipo	¿Obligatorio?	Descripción
`TrxToken`	`string`	No¹	Token de la tarjeta, generado previamente mediante el flujo de tokenización. Se usa para medios de pago - Tarjetas.
`NetworkToken`	`object`	No¹	Información del token de red utilizado en la transacción. Más detalles en la sección Tokenización de Red.
`PaymentMethodId`	`string`	No¹	Identificador del medio de pago. Se usa solo para medios de pago alternativos (transferencia, efectivo, etc.). Encuentre los valores posibles en la tabla medios de pago.
`UniqueID`	`string`	No	Identificador único de la compra del lado del comercio. Este valor es opcional y permite identificar una compra de forma única, evitando transacciones duplicadas. Para más información, consulte Conceptos.
`Capture`	`boolean`	No	Define si la compra debe realizarse en uno o dos pasos.² Si es `false`, solo se procesa la autorización, y la compra queda pre-autorizada hasta la confirmación final mediante las llamadas de captura y cancelación. Si es `true`, la transacción se autoriza y captura. Es posible que no todos los medios de pago y países admitan la función de pre-autorización.
`TargetCountryISO`	`string`	Sí	Este parámetro indica el país donde se procesará el pago. Envíe el país usando el formato `ISO-3166-1`.
`Currency`	`string`	Sí	Moneda de la compra, según ISO-4217. Encuentre los valores posibles en la tabla de Monedas de cada país.
`Amount`	`integer` (64 bits)	Sí	Monto de la compra. Es un valor mayor a cero. Si debe incluir decimales en el monto, concatene los lugares decimales sin el punto decimal. Ejemplo `12,25` → `1225`.
`Tip`	`integer` (64 bits)	No	Valor de la propina en la transacción. Valor con dos decimales, sin puntos ni comas.
`TaxableAmount`	`integer` (64 bits)	No	Valor de los impuestos de la transacción. Valor con dos decimales, sin puntos ni comas.
`Installments`	`integer`	No	Número de cuotas.
`Order`	`string`	Sí	Número de orden generado por el comercio.
`InvoiceNumber`	`string`	No	Número de factura asociado a la transacción.
`Description`	`string`	No ⁴	Descripción opcional de la compra.
`AdditionalData`	`string`	No	Información adicional que pueda ser relevante para la transacción.
`MetadataIn`	`object`	No	Datos adicionales de la transacción en formato clave-valor.
`Customer`	`object`	Sí ³	El objeto `Customer` proporciona los datos de la persona que realiza la compra.

Objeto Customer

Parámetro	Tipo	¿Obligatorio?	Descripción
`Customer` → `FirstName`	`string`	No	Nombre del cliente.
`Customer` → `LastName`	`string`	No	Apellido del cliente.
`Customer` → `ReferenceCode`	`string`	No	Código de referencia del cliente.
`Customer` → `PhoneNumber`	`string`	No	Número de teléfono del cliente.
`Customer` → `DocumentNumber`	`string`	No	Número de documento del cliente.
`Customer` → `DocumentType`	`string`	No	Tipo de documento. (Formato `DOCUMENTO`.`PAÍS`)
`Customer` → `Email`	`string`	Sí	Dirección de correo electrónico del cliente.
`Address`	`object`	No	Dirección de envío del cliente.

Objeto Address

Parámetro	Tipo	¿Obligatorio?	Descripción
`Address` → `Country`	`string`	No	País de la dirección del cliente.
`Address` → `City`	`string`	No	Ciudad de la dirección del cliente.
`Address` → `State`	`string`	No	Estado o región de la dirección del cliente.
`Address` → `PostalCode`	`string`	No	Código postal de la dirección del cliente.
`Address` → `AddressDetail`	`string`	No	Detalles adicionales de la dirección del cliente.

Notas

¹ Los parámetros PaymentMethodId y TrxToken no son obligatorios. Sin embargo, es obligatorio enviar uno de ellos, dependiendo del flujo que desee utilizar.
² Es posible que no todos los medios de pago admitan la función de pre-autorización. Revise la sección de Países y medios de pago para verificar la disponibilidad.
³ Este objeto no es obligatorio si crea la compra utilizando CommerceToken.
⁴ Al utilizar tarjetas en Brasil, la descripción es obligatoria y debe usar un formato fijo, como se explica en los parámetros de solicitud.
Tenga en cuenta que para el correcto funcionamiento del sistema Anti-fraude, le sugerimos enviar los datos adicionales descritos en la sección de Anti-fraude.
Para obtener información detallada sobre los objetos 3D Secure - 3DS y Network Token, consulte sus secciones correspondientes en esta documentación. PaymentMethod es obligatorio cuando se envía un Network Token.

Ejemplo de solicitud

{
    "TrxToken": "OT__6dHAgJo6qeg62qIroA7H7_f_NWZZ6IEx4jiYpVJ8SzQ_",
    "UniqueID": "paymentID3022",
    "Capture": true,
    "TargetCountryISO": "BR",
    "Currency": "BRL",
    "Amount": 25000,
    "Installments": 2,
    "Order": "CH2023-001",
    "Description": "Compra de teste",
    "Customer": {
        "FirstName": "João",
        "LastName": "Silva",
        "ReferenceCode": "JS-001",
        "PhoneNumber": "11987654321",
        "DocumentNumber": "12345678901",
        "DocumentType": "CPF.BR",
        "Email": "joao.silva@example.com",
        "Address": {
            "Country": "BR",
            "City": "São Paulo",
            "State": "SP",
            "PostalCode": "01310-200",
            "AddressDetail": "Avenida Paulista 1000"
        }
    }
}

Compra para Comercios con Certificación PCI

Para los comercios que tienen la certificación PCI-DSS, Bamboo ofrece una mayor flexibilidad a través del método de Compra Directa. Esta opción permite a los comercios con certificación PCI manejar los datos de las tarjetas directamente.

Versiones anteriores de la API

La documentación de la API versión V1 y V2 está disponible en la sección de Legacy

URL de la solicitud

Debe realizar una petición POST a las siguientes URLs según sus necesidades:

Producción: https://secure-api.bamboopayment.com/v3/api/purchase
Pruebas: https://secure-api.stage.bamboopayment.com/v3/api/purchase

Parámetros de la solicitud

Objeto CardData

Parámetro	Tipo	¿Obligatorio?	Descripción
`CardHolderName`	`string`	Sí	El nombre del titular tal como aparece en la tarjeta.
`Pan`	`string`	Sí	El número de tarjeta (PAN).
`CVV`	`string`	Sí	El código de verificación (CVV) o código de seguridad de la tarjeta.
`Expiration`	`string`	Sí	La fecha de vencimiento de la tarjeta en el formato “MM/AA”.
`Email`	`string`	Sí	Correo electrónico asociado al titular de la tarjeta.
`Document`	`string`	No	El número de documento de identidad del titular de la tarjeta.

Información

Nota: El objeto CardData solo debe utilizarse para transacciones con tarjetas no tokenizadas. Los datos sensibles de las tarjetas se deben manejar de forma segura y en cumplimiento con los estándares PCI DSS.

Ejemplo de solicitud

{
    "CardData": {
        "CardHolderName": "João Silva",
        "Pan": "4507990000004905",
        "CVV": "123",
        "Expiration": "08/30",
        "Email": "joao.silva@example.com",
        "Document": "12345678901"
    },
    "UniqueID": "paymentID3022",
    "Capture": true,
    "TargetCountryISO": "BR",
    "Currency": "BRL",
    "Amount": 25000,
    "Installments": 2,
    "Order": "CH2023-001",
    "Description": "Compra de teste",
    "Customer": {
        "FirstName": "João",
        "LastName": "Silva",
        "ReferenceCode": "JS-001",
        "PhoneNumber": "11987654321",
        "DocumentNumber": "12345678901",
        "DocumentType": "CPF.BR",
        "Email": "joao.silva@example.com",
        "Address": {
            "Country": "BR",
            "City": "São Paulo",
            "State": "SP",
            "PostalCode": "01310-200",
            "AddressDetail": "Avenida Paulista 1000"
        }
    }
}

Los campos CardData, PaymentMethodId, NetworkToken y TrxToken no son obligatorios; sin embargo, se debe enviar uno de ellos dependiendo del flujo que desee utilizar.

Respuesta del Request.

La respuesta para las operaciones de compra directa realizadas por comercios con certificación PCI es idéntica a la respuesta de la compra estándar. Esto asegura la consistencia entre los diferentes tipos de transacciones y simplifica los procesos de integración.

Todos los campos, estados y códigos de error descritos en la respuesta de Compra estándar se aplican por igual a las transacciones de Compra Directa.

Parámetro	Tipo	Descripción
`TransactionId`	`string`	Identificador único de la transacción. Un número de 19 dígitos.
`Result`	`string`	Resultado de la transacción. `COMPLETED` o `ACTION_REQUIRED`. Para más detalles, consulte el objeto “Action”.
`Status`	`string`	Estado actual de la transacción (por ejemplo, APPROVED, REJECTED).
`ErrorCode`	`string`	Código de error, si la transacción fue rechazada.
`ErrorDescription`	`string`	Descripción detallada del error si la transacción fue rechazada.
`Created`	`string`	Fecha / Hora en la que se creó la transacción, en formato ISO 8601.
`AuthorizationDate`	`string`	Fecha / Hora en la que se autorizó la transacción, en formato ISO 8601.
`AuthorizationCode`	`string`	Código único proporcionado por el adquirente / emisor para confirmar la autorización de la transacción.
`Amount`	`integer`	Valor total de la transacción.
`Currency`	`string`	Moneda utilizada para la transacción. Puede diferir de la moneda de la solicitud según el pricing configurado.
`Installments`	`integer`	Número de cuotas.
`TaxableAmount`	`integer`	Valor de los impuestos.
`Tip`	`integer`	Valor de la propina.
`Url`	`string`	URL con los detalles adicionales de la transacción.
`MetadataOut`	`object`	Metadatos adicionales de la respuesta de la transacción.
`Action`	`object`	Detalles de las acciones requeridas cuando el Resultado es “ACTION_REQUIRED”.
`PaymentMethod`	`object`	Medio de pago utilizado para la transacción.

Objeto Action

El objeto Action contiene información sobre los pasos adicionales requeridos para completar una transacción. Normalmente se envía en la respuesta cuando el resultado de la transacción es “ACTION_REQUIRED”, indicando que se necesita una acción adicional del usuario o del comercio para finalizar el pago.

Parámetro	Tipo	Descripción
`SessionId`	`string`	ID de sesión relacionado con la acción. Valor informativo.
`Reason`	`string`	Razón de la acción solicitada. Valores posibles: • `VERIFICATION_CODE_NEEDED:` Transacción pendiente de CVV, se requiere redirección a la “URL” para mostrar el formulario de ingreso del CVV. • `REDIRECTION_NEEDED_EXTERNAL_SERVICE`: Se requiere una redirección a la “URL” para completar los detalles de la transacción.
`URL`	`string`	URL de redirección para completar la acción requerida.

Objeto PaymentMethod

El objeto PaymentMethod contiene información detallada sobre el medio de pago utilizado en la transacción. Esto incluye detalles de la tarjeta (para transacciones con tarjeta) u otra información relevante del medio de pago.

Parámetro	Tipo	Descripción
`Brand`	`string`	Franquicia de la tarjeta utilizada (por ejemplo, MasterCard, Visa).
`CardOwner`	`string`	Nombre del titular de la tarjeta.
`Bin`	`string`	Primeros 6 dígitos del número de la tarjeta.
`IssuerBank`	`string`	Banco emisor de la tarjeta.
`Type`	`string`	Tipo de medio de pago (por ejemplo, CreditCard, DebitCard).
`Expiration`	`string`	Fecha de vencimiento de la tarjeta en formato aaaaMM.
`Last4`	`string`	Últimos 4 dígitos del número de la tarjeta.

Ejemplos de respuesta

Resultado: COMPLETED - Estado: APPROVED

{
    "TransactionId": "79632697147789184",
    "Result": "COMPLETED",
    "Status": "APPROVED",
    "ErrorCode": null,
    "ErrorDescription": null,
    "Created": "2024-08-07T17:51:54.620",
    "AuthorizationDate": "2024-08-07T17:51:56.879",
    "AuthorizationCode": "839936",
    "Amount": 25000,
    "Currency": "BRL",
    "Installments": 1,
    "TaxableAmount": null,
    "Tip": null,
    "Url": "https://api.stage.bamboopayment.com/Purchase/79632697147789184",
    "MetadataOut": null,
    "Action": null,
    "PaymentMethod": {
        "Brand": "Visa",
        "CardOwner": "Joao Silva",
        "Bin": "450799",
        "IssuerBank": "Santander",
        "Type": "CreditCard",
        "Expiration": "203008",
        "Last4": "4905"
    }
}

Resultado: COMPLETED - Estado: REJECTED

{
    "TransactionId": "79632697147789184",
    "Result": "COMPLETED",
    "Status": "REJECTED",
    "ErrorCode": "TR026",
    "ErrorDescription": "Insufficient Funds",
    "Created": "2024-08-07T17:51:54.620",
    "AuthorizationDate": "2024-08-07T17:51:56.879",
    "AuthorizationCode": "839936",
    "Amount": 25000,
    "Currency": "USD",
    "Installments": 2,
    "TaxableAmount": null,
    "Tip": null,
    "Url": "https://api.stage.bamboopayment.com/Purchase/79632697147789184",
    "MetadataOut": null,
    "Action": null,
    "PaymentMethod": {
        "Brand": "Visa",
        "CardOwner": "Joao Silva",
        "Bin": "450799",
        "IssuerBank": "Santander",
        "Type": "CreditCard",
        "Expiration": "203008",
        "Last4": "4905"
    }
}

Resultado: ACTION_REQUIRED - Estado: PENDING

{
    "TransactionId": "79632697147789184",
    "Result": "ACTION_REQUIRED",
    "Status": "PENDING",
    "ErrorCode": null,
    "ErrorDescription": null,
    "Created": "2024-08-07T17:51:54.620",
    "AuthorizationDate": null,
    "AuthorizationCode": null,
    "Amount": 25000,
    "Currency": "BRL",
    "Installments": 2,
    "TaxableAmount": null,
    "Tip": null,
    "Url": "https://api.stage.bamboopayment.com/Purchase/79632697147789184",
    "MetadataOut": null,
    "Action": {
        "SessionId": "CA_a4032a2a-25ae-4f5f-a8bb-fb2e5ab2ae3c",
        "URL": "https://url_to_be_redirected.com/redirection_example",
        "Reason": "VERIFICATION_CODE_NEEDED"
    },
    "PaymentMethod": {
        "Brand": "Visa",
        "CardOwner": "Joao Silva",
        "Bin": "450799",
        "IssuerBank": "Santander",
        "Type": "CreditCard",
        "Expiration": "203008",
        "Last4": "4905"
    }
}

{
   "ErrorCode": "PR001",
   "ErrorDescription": "The token sent is invalid, expired, or does not belong to the merchant."
}

Última modificación 22 de noviembre de 2024