Compras
Configurar la autenticación
Todos los métodos utilizados en la API de Compras requieren los siguientes encabezados de autenticación.
Llave | Valor | Comentarios |
---|---|---|
Content-Type | application/json | Con este encabezado, el request se transmite en formato JSON. |
Authorization | Basic {{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ódigo | Idioma |
---|---|
en | Inglé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. |
es | Español. |
pt | Portugué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ámetro | Tipo | ¿Obligatorio? | Descripción |
---|---|---|---|
PaymentMediaId | integer | No 1 | Corresponde 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). |
TrxToken | string | No 1 | Este parámetro se refiere al token utilizado para identificar la tarjeta del cliente. |
Order | string | Sí | Número de orden generado por el comercio. |
Amount | number | Sí | Monto 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 . |
Currency | string | Sí | Moneda de la compra de acuerdo con el formato ISO-4217. Encuentre los posibles valores en la tabla de Monedas de cada país. |
Installments | integer | No | Este parámetro hace referencia al número de pagos en el que se divide una compra con tarjeta de crédito. |
Capture | boolean | No | Define si la compra debe ser realizada en uno o dos pasos.2
No todos los medios de pago y países soportan la funcionalidad de preautorización. |
TargetCountryISO | string | Sí | Este parámetro indica el país donde se procesa la compra. Envíe el país usando el formato ISO-3166-1 . |
MetadataIn | object | No | Corresponde a los campos adicionales requeridos por cada medio de pago o adquirente. |
Customer | object | Sí 3 | El objeto Customer contiene la información de la persona que realiza la compra. |
Customer → CommerceCustomerId | string | No | Identificador del cliente. El comercio genera y utiliza este valor internamente para identificar al cliente dentro de la plataforma de Bamboo Payment. |
Customer → Email | string | Sí | Dirección de correo electrónico del cliente. |
Customer → FirstName | string | No | Nombre del cliente. |
Customer → LastName | string | No | Apellido del cliente. |
Customer → PhoneNumber | string | No | Número de teléfono de contacto del cliente. |
Customer → Enabled | boolean | No | Indica si el usuario está activo para operar. El valor predeterminado es true . |
Customer → BillingAddress | object | No | Este parámetro es la dirección de facturación del cliente. |
Customer → BillingAddress →AddressID | integer | No | Identificador de la dirección. |
Customer → BillingAddress →AddressType | string | No | Tipo de dirección. |
Customer → BillingAddress →Country | string | No | País de la dirección. |
Customer → BillingAddress →State | string | No | Estado de la dirección. |
Customer → BillingAddress →City | string | No | Ciudad de la dirección. |
Customer → BillingAddress →AddressDetail | string | No | Este parámetro corresponde a la información adicional de la dirección, como calle, número, etc. |
Customer → BillingAddress →PostalCode | string | No | Código postal de la dirección. |
Customer → ShippingAddress | object | No | Direcció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 . |
Customer → AdditionalData | string | No | Lista de tipo clave:valor para almacenar información adicional. |
Customer → CaptureURL | string | No | URL 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. |
Customer → DocumentTypeId | string | No | Tipo de documento del cliente. Encuentre los posibles valores en la tabla de Tipos de documento de cada país. |
Customer → DocNumber | string | No | Número de documento del cliente. |
Tip | number | No | Propina adicional de la compra si es necesaria. |
Description | string | No 4 | Descripción de la compra. |
UniqueID | string | No | Identificador ú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. |
AdditionalData | string | No | Puede 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. |
CustomerUserAgent | string | No | User 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. |
Notas
- 1 Los parámetros
PaymentMediaId
yTrxToken
no son obligatorios. Sin embargo, es obligatorio enviar uno de ellos dependiendo del flujo que desee utilizar. - 2 No todos los medios de pago soportan la funcionalidad de preautorización. Revise la sección de Países y medios de pago para verificar la disponibilidad.
- 3 No se requiere este objeto cuando cree una compra utilizando CommerceToken.
- 4 Cuando utilice tarjetas en Brasil, la descripción es obligatoria y debe utilizar un formato fijo, como se explica en los parámetros del request.
- Tenga en cuenta que para el correcto funcionamiento del sistema antifraude, sugerimos enviar la información adicional descrita en la sección Antifraude.
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.
Nota
No todos los medios de pago soportan la funcionalidad de preautorización y está disponible en los siguientes países
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.
Nota
Todos los parámetros son opcionales. Si no envía ningún parámetro, se mostrarán todas las compras de hoy.
Parámetro | Tipo | Descripción | |
---|---|---|---|
Authorized | boolean | Si el valor es true , retorna solo las compras que se hayan completado satisfactoriamente. | |
From | date | Fecha de inicio del filtro. Formato: yyyyMMdd . | |
OrderNumber | string | Número de orden del comercio. | |
PaymentMediaId | integer | Identificador del medio de pago usado en la compra. | |
To | date | Fecha 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ámetro | Tipo | Descripción |
---|---|---|
Response | object | Parámetros retornados como resultado del procesamiento de una compra. |
Response → PurchaseId | integer | Identificador de la compra. |
Response → Created | date | Fecha y hora en la que se creó la compra. Formato de la fecha ISO-8601. |
Response → Transaction | object | Este objeto está asociado con la compra y contiene la información del request enviado y el response obtenido desde el medio de pago correspondiente. |
Response → Transaction → TransactionID | integer | Identificador de la transacción. |
Response → Transaction → Created | date | Fecha y hora en la que se creó la transacción. Formato de la fecha ISO-8601. |
Response → Transaction → TransactionStatusId | integer | Identificador interno del estado de la transacción. |
Response → Transaction → Status | string | Estado actual de la transacción. |
Response → Transaction → ErrorCode | string | Código de error (si aplica) retornado por el medio de pago. |
Response → Transaction → Description | string | Descripción del resultado de la transacción. |
Response → Transaction → ApprovalCode | string | Código de aprobación retornado por el medio de pago. |
Response → RefundList | object | Este objeto contiene información sobre los reembolsos de la compra (parciales o totales). |
Response → RefundList → PurchaseRefundId | integer | Identificador asociado con el reembolso. |
Response → RefundList → Created | date | Fecha y hora en la que se creó el reembolso. |
Response → RefundList → UniqueID | string | Identificador único de la transacción. Este valor permite identificar un reembolso en la lista de todos los posibles reembolsos realizados. |
Response → RefundList → Amount | integer | Monto total del reembolso. |
Response → RefundList → Currency | string | Moneda de la compra de acuerdo al formato ISO-4217 (códigos alfanuméricos). |
Response → RefundList → Status | string | Estado actual del reembolso. |
Response → CommerceAction | object | Este objeto informa al comercio o al cliente la acción que debe llevar a cabo para completar el proceso de compra actual. |
Response → MetadataOut | object | Campos 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. |
Response → CrossBorderDataResponse | object | Este objeto contiene información sobre los montos procesados en la moneda local del país seleccionado. |
Response → CrossBorderDataResponse → TargetCountryISO | string | Mismo país enviado en el request. |
Response → CrossBorderDataResponse → TargetCurrencyISO | string | Moneda local determinada para el país seleccionado. |
Response → CrossBorderDataResponse → TargetAmount | number | Monto de compra convertido a la moneda local. |
Errors | list | Lista de errores que el sistema puede lanzar durante el proceso de compra. |
Errors → ErrorCode | string | Código de error retornado. |
Errors → Created | string | Fecha y hora en la que se generó el error. |
Errors → Message | string | Texto descriptivo del error. |
Errors → Detail | string | Detalle 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": []
}