Compras

Cree una compra utilizando el utilizando el flujo API proporcionando su información básica. Además, explore las distintas operaciones disponibles para las compras existentes.

Configurar la autenticación

Todos los métodos utilizados en la API de Compras requieren los siguientes encabezados de autenticación.

LlaveValorComentarios
Content-Typeapplication/jsonCon este encabezado, el request se transmite en formato JSON.
AuthorizationBasic {{Merchant Private Key}}Envíe el {{Merchant Private Key}} (su identificador de comercio) y la palabra Basic.
Ejemplo: Basic RVkeLr-86_iTzSMLvDtuyQ-1zqIcsmFG-oSzncn_uFv-nj7bhB3rtZg__

Configurar el idioma de los códigos de respuesta

Puede recibir la descripción del error basándose en las funciones de localización. Para ello, debe enviar el encabezado lang en su integración, utilizando cualquiera de los siguientes idiomas en formato ISO 639-1.

CódigoIdioma
enInglés.
Este es el idioma por defecto. Si no envía este encabezado o envía un idioma diferente a los soportados, recibirá los errores en este idioma.
esEspañol.
ptPortugués.

Métodos de la API de Compras

Las siguientes operaciones expuestas por la API de Compras le permite realizar varias acciones sobre las compras. Usted cuenta con los siguientes métodos.

Crear una compra

Cree una compra básica en Bamboo Payment.

URL del Request

Debe invocar un request POST a las siguientes URL de acuerdo con sus necesidades.

  • Producción: https://api.bamboopayment.com/v1/api/purchase
  • Stage: https://api.stage.bamboopayment.com/v1/api/purchase

Parámetros del Request

ParámetroTipo¿Obligatorio?Descripción
PaymentMediaIdintegerNo 1Corresponde al ID del medio de pago que quiere utilizar. Este parámetro es solo para Métodos Alternativos de Pagos (transferencia, efectivo y procesamiento que requieren redirección del cliente).
TrxTokenstringNo 1Este parámetro se refiere al token utilizado para identificar la tarjeta del cliente.
OrderstringNúmero de orden generado por el comercio.
AmountnumberMonto de la compra. Este valor debe ser mayor a cero.
Si debe incluir decimales, concatene los dígitos decimales sin el punto decimal. Ejemplo 12,25 > 1225.
CurrencystringMoneda de la compra de acuerdo con el formato ISO-4217. Encuentre los posibles valores en la tabla de Monedas de cada país.
InstallmentsintegerNoEste parámetro hace referencia al número de pagos en el que se divide una compra con tarjeta de crédito.
CapturebooleanNoDefine si la compra debe ser realizada en uno o dos pasos.2
  • Si es false, solo se procesa la autorización y la compra queda preautorizada hasta que se realice la confirmación final a través de los métodos confirmar o anular.
  • Si es true, la transacción es autorizada y capturada (confirmada).

No todos los medios de pago y países soportan la funcionalidad de preautorización.
TargetCountryISOstringEste parámetro indica el país donde se procesa la compra.
Envíe el país usando el formato ISO-3166-1.
MetadataInobjectNoCorresponde a los campos adicionales requeridos por cada medio de pago o adquirente.
Customerobject3El objeto Customer contiene la información de la persona que realiza la compra.
CustomerCommerceCustomerIdstringNoIdentificador del cliente.
El comercio genera y utiliza este valor internamente para identificar al cliente dentro de la plataforma de Bamboo Payment.
CustomerEmailstringDirección de correo electrónico del cliente.
CustomerFirstNamestringNoNombre del cliente.
CustomerLastNamestringNoApellido del cliente.
CustomerPhoneNumberstringNoNúmero de teléfono de contacto del cliente.
CustomerEnabledbooleanNoIndica si el usuario está activo para operar. El valor predeterminado es true.
CustomerBillingAddressobjectNoEste parámetro es la dirección de facturación del cliente.
CustomerBillingAddressAddressIDintegerNoIdentificador de la dirección.
CustomerBillingAddressAddressTypestringNoTipo de dirección.
CustomerBillingAddressCountrystringNoPaís de la dirección.
CustomerBillingAddressStatestringNoEstado de la dirección.
CustomerBillingAddressCitystringNoCiudad de la dirección.
CustomerBillingAddressAddressDetailstringNoEste parámetro corresponde a la información adicional de la dirección, como calle, número, etc.
CustomerBillingAddressPostalCodestringNoCódigo postal de la dirección.
CustomerShippingAddressobjectNoDirección de envío del cliente. Esta direccion es la que el cliente indica para recibir el producto adquirido. Este objeto tiene los mismos parámetros que el objeto Customer.BillingAddress.
CustomerAdditionalDatastringNoLista de tipo clave:valor para almacenar información adicional.
CustomerCaptureURLstringNoURL de captura de datos de la tarjeta.
Este parámetro contiene la URL que debe cargarse en un iframe para iniciar el proceso seguro de captura de datos.
Esto sólo se aplica a Clientes de tipo Commerce.
CustomerDocumentTypeIdstringNoTipo de documento del cliente. Encuentre los posibles valores en la tabla de Tipos de documento de cada país.
CustomerDocNumberstringNoNúmero de documento del cliente.
TipnumberNoPropina adicional de la compra si es necesaria.
DescriptionstringNo 4Descripción de la compra.
UniqueIDstringNoIdentificador único de la compra.
Este valor es opcional y le permite identificar una compra de forma única y evitar duplicación de transacciones en caso de errores de comunicación. Para más información, consulte Conceptos.
AdditionalDatastringNoPuede agregar información adicional a la transacción (Por ejemplo una lista de datos Clave:Valor).
Esta información se retorna cada vez que se consulta la compra.
CustomerUserAgentstringNoUser Agent del cliente que utiliza el servicio; para dispositivos de escritorio, debe ser el UserAgent informado por el navegador, y para móviles, la información sobre el dispositivo, S.O. utilizado y nombre de la App.
Ejemplo del Request
{
  "TrxToken":"OT__zq4aTY4T9TzSldeBKry-Wbx75QNbuT894jiYpVJ8SzQ_",
  "Order": "099927564",
  "Capture": true,
  "Amount": "10000",
  "Currency": "UYU",
  "TargetCountryISO": "UY",
  "Installments": 1,
  "Customer": {
    "Email": "john@mail.com",
    "FirstName": "John",
    "LastName": "Smith",
    "DocNumber": "12345672",
    "DocumentTypeId": 2,
    "PhoneNumber": "24022330",
    "BillingAddress": {
      "AddressType": 1,
      "Country": "Uruguay",
      "State": "Montevideo",
      "City": "MONTEVIDEO",
      "AddressDetail": "Av. Sarmiento 2260",
      "PostalCode": "150000"
    }
  },
  "DataUY": {
    "IsFinalConsumer": "true",
    "Invoice": "1000",
    "TaxableAmount": 0
  }
}

Confirmar una compra

Este método le permite confirmar una compra preautorizada.

URL del Request

Debe invocar un request POST a las siguientes URL de acuerdo con sus necesidades.

  • Producción: https://api.bamboopayment.com/v1/api/purchase/{{PurchaseID}}/commit
  • Stage: https://api.stage.bamboopayment.com/v1/api/purchase/{{PurchaseID}}/commit

Parámetros del Request

El cuerpo del request es opcional para confirmar una compra. Si no envía el request, el método confirma la compra preautorizada por su monto original.

El monto de la compra puede variar respecto al enviado en el proceso de compra inicial, pero el nuevo monto no puede ser superior al original.

Ejemplo del Request

Debe incluir el nuevo monto en la solicitud para confirmar una compra con un monto inferior al original. Por ejemplo:

{
  "Amount": 50
}

Obtener compras

Este método le permite obtener la información de una o más compras según el criterio de búsqueda enviado en el cuerpo del mismo.

URL del Request

Debe invocar un request GET a las siguientes URL de acuerdo con sus necesidades.

  • Producción: https://api.bamboopayment.com/v1/api/purchase
  • Stage: https://api.stage.bamboopayment.com/v1/api/purchase

Para obtener una compra específica, incluya /{{PurchaseID}} en la URL. Ejemplo: https://api.bamboopayment.com/v1/api/purchase/481561.

Parámetros del Request

Los siguientes parámetros son necesarios cuando desea obtener una lista de compras. Agregue el PurchaseID a la URL del request cuando quiera quiera obtener una compra específica.

ParámetroTipoDescripción
AuthorizedbooleanSi el valor es true, retorna solo las compras que se hayan completado satisfactoriamente.
FromdateFecha de inicio del filtro.
Formato: yyyyMMdd.
OrderNumberstringNúmero de orden del comercio.
PaymentMediaIdintegerIdentificador del medio de pago usado en la compra.
TodateFecha de fin del filtro.
Formato: yyyyMMdd.

Parámetros del Response

Obtendrá el mismo objeto Response independientemente del método que invoque. Sólo cuando consulte compras y el resultado tenga múltiples resultados el Response retornado será un array.

La siguiente tabla describe los parámetros del objeto Response relevantes para la compra, sus posibles siguientes pasos en el flujo y los errores que se pueden haber generado.

ParámetroTipoDescripción
ResponseobjectParámetros retornados como resultado del procesamiento de una compra.
ResponsePurchaseIdintegerIdentificador de la compra.
ResponseCreateddateFecha y hora en la que se creó la compra.
Formato de la fecha ISO-8601.
ResponseTransactionobjectEste objeto está asociado con la compra y contiene la información del request enviado y el response obtenido desde el medio de pago correspondiente.
ResponseTransactionTransactionIDintegerIdentificador de la transacción.
ResponseTransactionCreateddateFecha y hora en la que se creó la transacción.
Formato de la fecha ISO-8601.
ResponseTransactionTransactionStatusIdintegerIdentificador interno del estado de la transacción.
ResponseTransactionStatusstringEstado actual de la transacción.
ResponseTransactionErrorCodestringCódigo de error (si aplica) retornado por el medio de pago.
ResponseTransactionDescriptionstringDescripción del resultado de la transacción.
ResponseTransactionApprovalCodestringCódigo de aprobación retornado por el medio de pago.
ResponseRefundListobjectEste objeto contiene información sobre los reembolsos de la compra (parciales o totales).
ResponseRefundListPurchaseRefundIdintegerIdentificador asociado con el reembolso.
ResponseRefundListCreateddateFecha y hora en la que se creó el reembolso.
ResponseRefundListUniqueIDstringIdentificador único de la transacción.
Este valor permite identificar un reembolso en la lista de todos los posibles reembolsos realizados.
ResponseRefundListAmountintegerMonto total del reembolso.
ResponseRefundListCurrencystringMoneda de la compra de acuerdo al formato ISO-4217 (códigos alfanuméricos).
ResponseRefundListStatusstringEstado actual del reembolso.
ResponseCommerceActionobjectEste objeto informa al comercio o al cliente la acción que debe llevar a cabo para completar el proceso de compra actual.
ResponseMetadataOutobjectCampos adicionales retornados por cada medio de pago o adquirente para realizar los siguientes pasos.
Por ejemplo, este objeto puede contener la URL a la que debe redirigir al cliente o la imagen QR que el cliente debe escanear.
ResponseCrossBorderDataResponseobjectEste objeto contiene información sobre los montos procesados en la moneda local del país seleccionado.
ResponseCrossBorderDataResponseTargetCountryISOstringMismo país enviado en el request.
ResponseCrossBorderDataResponseTargetCurrencyISOstringMoneda local determinada para el país seleccionado.
ResponseCrossBorderDataResponseTargetAmountnumberMonto de compra convertido a la moneda local.
ErrorslistLista de errores que el sistema puede lanzar durante el proceso de compra.
ErrorsErrorCodestringCódigo de error retornado.
ErrorsCreatedstringFecha y hora en la que se generó el error.
ErrorsMessagestringTexto descriptivo del error.
ErrorsDetailstringDetalle del error.

Ejemplo del Response

{
    "Response": {
        "PurchaseId": 481561,
        "Created": "2023-08-01T20:53:28.309",
        "TrxToken": null,
        "Order": "099927564",
        "Transaction": {
            "TransactionID": 499285,
            "Created": "2023-08-01T20:53:28.310",
            "AuthorizationDate": "2023-08-01T20:53:28.737",
            "TransactionStatusId": 1,
            "Status": "Approved",
            "ErrorCode": null,
            "Description": "",
            "ApprovalCode": "831000",
            "Steps": [
                {
                    "Step": "Generic External",
                    "Created": "2023-08-01T20:53:28.650",
                    "Status": "Authorization OK - Step 1",
                    "ResponseCode": "200",
                    "ResponseMessage": "OK",
                    "Error": "",
                    "AuthorizationCode": null,
                    "UniqueID": null,
                    "AcquirerResponseDetail": "{\"card\":{\"type\":\"C\",\"issuer\":\"424242\",\"isLocal\":true},\"allowedInstallments\":[1,2,3],\"currency\":858,\"authorizationAmount\":100.0,\"discountAmount\":0.0,\"discountPoints\":0,\"lawLimitApplied\":false,\"code\":0,\"message\":\"ok\"}"
                },
                {
                    "Step": "Generic External",
                    "Created": "2023-08-01T20:53:28.730",
                    "Status": "Authorization OK",
                    "ResponseCode": "100",
                    "ResponseMessage": "ACCEPT",
                    "Error": "",
                    "AuthorizationCode": "831000",
                    "UniqueID": null,
                    "AcquirerResponseDetail": "{\"Decision\":\"ACCEPT\",\"ReasonCode\":\"100\",\"RequestID\":\"386631747\",\"PaymentNetworkTransactionID\":\"016153570198200\",\"CvCode\":null,\"MerchantReferenceCode\":\"20201229\",\"AuthorizationCode\":\"831000\"}"
                }
            ]
        },
        "Capture": true,
        "Amount": 10000,
        "OriginalAmount": 10000,
        "TaxableAmount": 0,
        "Tip": 0,
        "Installments": 1,
        "Currency": "UYU",
        "Description": null,
        "Customer": {
            "CustomerId": 247720,
            "Created": "2023-08-01T20:53:16.073",
            "CommerceCustomerId": null,
            "Owner": "Anonymous",
            "Email": "john@mail.com",
            "Enabled": true,
            "ShippingAddress": {
                "AddressId": 0,
                "AddressType": 1,
                "Country": "Uruguay",
                "State": "Montevideo",
                "AddressDetail": "Av. Sarmiento 2260",
                "PostalCode": "150000",
                "City": "Montevideo"
            },
            "Plans": null,
            "AdditionalData": null,
            "PaymentProfiles": [
                {
                    "PaymentProfileId": 252393,
                    "PaymentMediaId": 1,
                    "Created": "2023-08-01T20:53:16.073",
                    "LastUpdate": null,
                    "Brand": "VISA",
                    "CardOwner": "John Smith",
                    "Bin": null,
                    "IssuerBank": "Visa",
                    "Installments": "1;2;3;4;5;6;7;8;9;10;11;12",
                    "Type": "CreditCard",
                    "IdCommerceToken": 0,
                    "Token": null,
                    "Expiration": "202605",
                    "Last4": "0001",
                    "Enabled": null,
                    "DocumentNumber": null,
                    "DocumentTypeId": null,
                    "ExternalValue": null,
                    "AffinityGroup": null
                }
            ],
            "CaptureURL": null,
            "UniqueID": null,
            "URL": "https://testapi.siemprepago.com/v1/api/Customer/247720",
            "FirstName": "John",
            "LastName": "Smith",
            "DocNumber": "12345672",
            "DocumentTypeId": 2,
            "PhoneNumber": "24022330",
            "ExternalValue": null
        },
        "RefundList": null,
        "PlanID": null,
        "UniqueID": null,
        "AdditionalData": null,
        "CustomerUserAgent": null,
        "CustomerIP": null,
        "URL": "https://testapi.siemprepago.com/v1/api/Purchase/481561",
        "DataUY": {
            "IsFinalConsumer": "true",
            "Invoice": "1000",
            "TaxableAmount": 0
        },
        "DataDO": null,
        "Acquirer": {
            "AcquirerID": 77,
            "Name": "VisaNetUYv2",
            "CommerceNumber": null
        },
        "CommerceAction": null,
        "PurchasePaymentProfileId": 252393,
        "LoyaltyPlan": null,
        "DeviceFingerprintId": null,
        "MetadataIn": null,
        "MetadataOut": null,
        "CrossBorderData": null,
        "CrossBorderDataResponse": null,
        "Redirection": null,
        "AntifraudData": {
            "AntifraudFingerprintId": null,
            "AntifraudMetadataIn": null
        },
        "PaymentMediaId": null,
        "TargetCountryISO": null,
        "PurchaseType": 1,
        "IsFirstRecurrentPurchase": false
    },
    "Errors": []
}
footer
Última modificación 18 de noviembre de 2024

© Bamboo | All rights reserved 2024