Operations

Create a purchase using the API flow providing its basic information. Furthermore, explore the different operations over existing purchases.

Configuring the authentication

All methods used in Purchase API require the following authentication headers.

Key	Value	Comments
`Content-Type`	`application/json`	With this header, the request will be transmitted in JSON format.
`Authorization`	`Basic {{Merchant Private Key}}`	Send the `{{Merchant Private Key}}` (your merchant identifier) and the word `Basic`. Example: `Basic RVkeLr-86_iTzSMLvDtuyQ-1zqIcsmFG-oSzncn_uFv-nj7bhB3rtZg__`

Setting the language of the response codes

You can receive the error description by relying on localization features. To do this, you need to send the lang header in your integration, using any of the following languages in ISO 639-1 format.

Code	Language
`en`	English. This is the default language. If you don’t send this header or set a non-existent language, you will receive errors in this language.
`es`	Spanish.
`pt`	Portuguese.

Purchase API methods

The operations exposed by the Purchase API allow you to perform several actions over Purchases. You have available the following methods.

Create a purchase
Confirm a purchase
Get purchases

Create a purchase

Create a basic purchase in Bamboo Payment.

Request URL

You must invoke a POST request to the following URLs according to your needs.

Production: https://api.bamboopayment.com/v1/api/purchase
Stage: https://api.stage.bamboopayment.com/v1/api/purchase

Request parameters

Parameter	Type	Mandatory?	Description
`PaymentMediaId`	`integer`	No ¹	Corresponds to the Id of the payment method you want to use. This parameter is only for Alternative payment methods (transfer, cash, and processing that requires customer redirection).
`TrxToken`	`string`	No ¹	This parameter refers to the token used to identify a customer’s card.
`Order`	`string`	Yes	Order number generated by the merchant.
`Amount`	`number`	Yes	Amount of the purchase. This value must be greater than zero. If you must include decimals in the amount, concatenate the decimal places without the decimal point. Example `12,25` > `1225`.
`Currency`	`string`	Yes	Currency of the purchase, according to ISO-4217. Find the possible values in the Currencies table of each country.
`Installments`	`integer`	No	This parameter refers to the number of payments that a credit card purchase is divided into.
`Capture`	`boolean`	No	Defines whether the purchase should be performed in one or two steps.² If `false`, only the authorization is processed, and the purchase is pre-authorized until the final confirmation through the commit and rollback calls. If `true`, the transaction is authorized and captured (committed). All payment methods and countries may not support the pre-authorization feature.
`TargetCountryISO`	`string`	Yes	This parameter indicates the country where the payment will be processed. Send the country using `ISO-3166-1` format.
`MetadataIn`	`object`	No	The Additional fields required by each payment method or acquirer.
`Customer`	`object`	Yes ³	The `Customer` object provides the data of the person who performs the purchase.
`Customer` → `CommerceCustomerId`	`string`	No	Customer identifier. The merchant generates and uses this value internally to identify the customer within the Bamboo Payment platform.
`Customer` → `Email`	`string`	Yes	Customer email address.
`Customer` → `FirstName`	`string`	No	Customer name.
`Customer` → `LastName`	`string`	No	Customer last name.
`Customer` → `PhoneNumber`	`string`	No	Customer contact telephone number.
`Customer` → `Enabled`	`boolean`	No	Indicates whether the user is enabled to operate. The default value is `true`.
`Customer` → `BillingAddress`	`object`	No	This parameter is the customer’s billing address.
`Customer` → `BillingAddress`→`AddressID`	`integer`	No	Address Identifier.
`Customer` → `BillingAddress`→`AddressType`	`string`	No	Type of address.
`Customer` → `BillingAddress`→`Country`	`string`	No	Country of the address.
`Customer` → `BillingAddress`→`State`	`string`	No	State of the address.
`Customer` → `BillingAddress`→`City`	`string`	No	City of the address.
`Customer` → `BillingAddress`→`AddressDetail`	`string`	No	This parameter corresponds to the Additional information of the address, such as street, number, etc.
`Customer` → `BillingAddress`→`PostalCode`	`string`	No	Postal Code of the address.
`Customer` → `ShippingAddress`	`object`	No	The customer’s shipping address. This address is where they want to receive their purchased product. This object has the same parameter as the `Customer.BillingAddress` object.
`Customer` → `AdditionalData`	`string`	No	List of type `key:value` to store extra information.
`Customer` → `CaptureURL`	`string`	No	Card data capture URL. This parameter contains the URL that should be loaded in an iframe to initiate the secure data capture process. This only applies to Customers of type Commerce.
`Customer` → `DocumentTypeId`	`string`	No	Customer document type. Find the possible values in the Document types table of each country.
`Customer` → `DocNumber`	`string`	No	Customer document Number.
`Tip`	`number`	No	Additional tip of the purchase if required.
`Description`	`string`	No ⁴	Optional description of the purchase.
`UniqueID`	`string`	No	Unique identifier of the purchase. This optional value allows you to identify a unique purchase and avoid duplication of transactions in case of communication errors. For more information, refer to Concepts.
`AdditionalData`	`string`	No	You can add additional information to the transaction (For example a `Key:Value` data list). We return this information each time you consult the purchase.
`CustomerUserAgent`	`string`	No	User Agent of the customer who uses the service; for desktop devices, it should be the `UserAgent` reported by the browser, and for mobile, the information about the device, S.O. used, and App name.

Notes

¹ The PaymentMediaId and TrxToken parameters are not required. Nevertheless, sending one of them is mandatory, depending on the flow you want to use.
² All the payment methods may not support the pre-authorization feature. Review the Countries and payment methods section to check availability.
³ This object is not required if you create the purchase using CommerceToken.
⁴ When using cards in Brazil, the description is mandatory and must use a fixed format, as explained in the request parameters.
Keep in mind that for the Anti-fraud system’s correct functioning, we suggest sending additional data described in the Anti-fraud section.

Request example

{
  "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
  }
}

Confirm a purchase

This method allows you to confirm a pre-authorized purchase.

Note

All payment methods may not support the pre-authorization feature, and it’s available for the following countries.

Request URL

You must invoke a POST request to the following URLs according to your needs.

Production: https://api.bamboopayment.com/v1/api/purchase/{{PurchaseID}}/commit
Stage: https://api.stage.bamboopayment.com/v1/api/purchase/{{PurchaseID}}/commit

Request parameters

The request body is optional to confirm a purchase. If you don’t send any request, the method commits the pre-authorized purchase by its original amount.

The purchase amount may vary concerning the one sent in the initial purchase process, but the new amount cannot be higher than the original amount.

Request example

You must include the new amount in the request to confirm a purchase with a lower amount than the original. For example:

{
  "Amount": 50
}

Get Purchases

This method allows you to get the information of one or more purchases given the search criteria sent in the body.

Request URL

You must invoke aGET request to the following URLs according to your needs.

Production: https://api.bamboopayment.com/v1/api/purchase
Stage: https://api.stage.bamboopayment.com/v1/api/purchase

To get a specific purchase, include in the URL /{{PurchaseID}}. Example: https://api.bamboopayment.com/v1/api/purchase/481561.

Request parameters

The following parameters are only required when you want to get a list of purchases. Add the PurchaseID to the Request URL when requesting a specific purchase.

Note

All the parameters are optional. If you don’t send any parameters, all today’s purchases will be listed.

Parameter	Type	Description
`Authorized`	`boolean`	If the value is `true`, it returns only purchases that have been completed successfully.
`From`	`date`	Filter start date. Format: `yyyyMMdd`.
`OrderNumber`	`string`	Merchant order number.
`PaymentMediaId`	`integer`	Identifier of the Payment Method used in the purchase.
`To`	`date`	Filter end date. Format: `yyyyMMdd`.

Response parameters

You will get the same Response object regardless of the method you invoke. Only when you query purchases and the result has multiple results the Response returned will be an array.

The following table describes the parameters in the Response object relevant to the purchase, its possible next steps in the flow, and the errors that may have occurred.

Parameter	Type	Description
`Response`	`object`	Parameters returned due to the purchase processing.
`Response` → `PurchaseId`	`integer`	Purchase identifier.
`Response` → `Created`	`date`	Date and time when the purchase was created. Date format ISO-8601.
`Response` → `Transaction`	`object`	This object is associated with the Purchase and has the information on the request sent and the response obtained from the corresponding payment method.
`Response` → `Transaction` → `TransactionID`	`integer`	Transaction identifier.
`Response` → `Transaction` → `Created`	`date`	Date and time when the transaction was created. Date format ISO-8601.
`Response` → `Transaction` → `TransactionStatusId`	`integer`	Internal identifier of the transaction status.
`Response` → `Transaction` → `Status`	`string`	Current status of the transaction.
`Response` → `Transaction` → `ErrorCode`	`string`	Error code (if applicable) returned by the payment method.
`Response` → `Transaction` → `Description`	`string`	Description of the outcome of the transaction.
`Response` → `Transaction` → `ApprovalCode`	`string`	Approval code returned by the payment method.
`Response` → `RefundList`	`object`	This object has information on the purchase’s refunds (partials or total).
`Response` → `RefundList` → `PurchaseRefundId`	`integer`	Identifier associated with the refund.
`Response` → `RefundList` → `Created`	`date`	Date and time when the refund was made.
`Response` → `RefundList` → `UniqueID`	`string`	Unique identifier of the transaction. This value allows you to identify a refund in the list of all possible refunds made.
`Response` → `RefundList` → `Amount`	`integer`	Total amount of the refund.
`Response` → `RefundList` → `Currency`	`string`	Currency of the purchase, according to ISO-4217 (alphanumeric codes).
`Response` → `RefundList` → `Status`	`string`	Current status of the refund.
`Response` → `CommerceAction`	`object`	This object informs you of the actions you or your customer must take to complete the current purchase process.
`Response` → `MetadataOut`	`object`	Additional fields returned by each payment method or acquirer to perform the following steps. For example, this object can have the URL to where you need to redirect the customer or the QR image that has to be scanned by your customer.
`Response` → `CrossBorderDataResponse`	`object`	This object has the information about the processed Amounts in the local currency of the selected Country.
`Response` → `CrossBorderDataResponse` → `TargetCountryISO`	`string`	Same country sent in the request.
`Response` → `CrossBorderDataResponse` → `TargetCurrencyISO`	`string`	Local currency determined for the selected country.
`Response` → `CrossBorderDataResponse` → `TargetAmount`	`number`	Purchase amount converted to the local currency.
`Errors`	`list`	List of errors that the system can launch during the purchase process.
`Errors` → `ErrorCode`	`string`	Error code returned.
`Errors` → `Created`	`string`	Date and time when the error was generated.
`Errors` → `Message`	`string`	Descriptive text of the error.
`Errors` → `Detail`	`string`	Error detail.

Response example

{
    "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": []
}

Last modified June 24, 2024