Recurring Use Token

Despite the Anonymous users, these users are registered on the website so that you can identify them, and their card information can be associated to perform other purchases without having to provide this information again.

The client receives a CommerceToken after registering their card, which can be used for future transactions. Below are the steps to purchase as a registered user on the website.

Create a Customer

The first step is to create the customer in Bamboo Payment. To do this, you need to send a POST request to the following URLs depending on your environment.

  • Production: https://api.bamboopayment.com/v1/api/customer
  • Stage: https://api.stage.bamboopayment.com/v1/api/customer

Request Parameters

ParameterTypeMandatory?Description
EmailstringYesCustomer email address.
FirstNamestringYesCustomer name.
LastNamestringYesCustomer last name.
DocumentTypeIdstringYesCustomer document type. Find for the Legacy version, the possible values in the Document types table according to the country.
DocNumberstringYesCustomer document Number.
OwnerstringNoIt determines whether the user is anonymous or if the merchant, or us, registered it.
The possible values are:
  • Our
  • Commerce. This is the default value
  • Anonymous
PhoneNumberstringYesCustomer contact telephone number.
BillingAddressobjectYesThis parameter is the customer’s billing address.
BillingAddressAddressIDintegerYesAddress Identifier.
BillingAddressAddressTypestringYesType of address.
BillingAddressCountrystringYesCountry of the address.
BillingAddressStatestringYesState of the address.
BillingAddressCitystringYesCity of the address.
BillingAddressAddressDetailstringYesThis parameter corresponds to the Additional information of the address, such as street, number, etc.

Request Example

{
    "Email": "kristeldyoder@teleworm.us",
    "FirstName": "Kristel",
    "LastName": "Yoder",
    "DocNumber": "31130749",
    "DocumentTypeId": 2,
    "Owner": "Commerce",
    "PhoneNumber": "093000000",
    "BillingAddress": {
        "AddressType": 1,
        "Country": "Uruguay",
        "State": "Montevideo",
        "City": "Montevideo",
        "AddressDetail": "100"
    }
}

Response Parameters

The response object returns the newly created customer’s information or any errors that may have occurred. The Response.CustomerId parameter contains the customer ID generated by the API, which can be used to query or update the customer.

Use the following parameters for additional operations on customers:

  • UniqueID: A temporary unique identifier used to register external payment methods. Each time you query the customer information, a new identifier is provided. For more details, see Invoking the Card Enrollment Form.
  • URL: URL for querying customer information. For more details, see Get a Customer.

Response Example

{
    "Response": {
        "CustomerId": 249205,
        "Created": "2023-08-22T11:26:53.343",
        "CommerceCustomerId": null,
        "Owner": "Commerce",
        "Email": "kristeldyoder@teleworm.us",
        "Enabled": true,
        "ShippingAddress": null,
        "BillingAddress": {
            "AddressId": 373151,
            "AddressType": 1,
            "Country": "Uruguay",
            "State": "Montevideo",
            "AddressDetail": "100",
            "PostalCode": null,
            "City": "Montevideo"
        },
        "Plans": null,
        "AdditionalData": null,
        "PaymentProfiles": [],
        "CaptureURL": "https://api.stage.bamboopayment.com/Capture/",
        "UniqueID": "UI_b53cb8db-771e-4622-a5db-0e58e156f192",
        "URL": "https://api.stage.bamboopayment.com/api/Customer/249205",
        "FirstName": "Kristel",
        "LastName": "Yoder",
        "DocNumber": "31130749",
        "DocumentTypeId": 2,
        "PhoneNumber": "093000000",
        "ExternalValue": null
    },
    "Errors": []
}

Customer Operations

Once a user is created, you can perform operations to retrieve or update their information.

Get a Customer

You can retrieve customer information using their ID or email address.

To do this, send a GET request to the following URLs based on your environment.

  • Production: https://api.bamboopayment.com/v1/api/customer
  • Stage: https://api.stage.bamboopayment.com/v1/api/customer
Endpoint
Get by Customer ID/{{customer-id}}
Get by Customer Email Address/email/{{EmailAddress}}

The response includes a list containing the same object returned when creating the customer.

Update a Customer

To update a customer’s information, send a POST request to the following URLs based on your environment.

  • Production: https://api.bamboopayment.com/v1/api/customer/{{customer-id}}/update
  • Stage: https://api.stage.bamboopayment.com/v1/api/customer/{{customer-id}}/update

Where {{customer-id}} is the ID generated when the user was created. Include the parameters you wish to update in the request body.

The response includes the same object returned when creating the customer.

Capturing Card Information

The next step is to obtain the customer’s card token. You can either invoke the card enrollment form or use Direct Tokenization if your business complies with PCI standards.

Invoking the Card Enrollment Form

To invoke the capture form for a previously created customer, follow these steps:

  1. Obtain the customer’s uniqueId by executing the Get Customer operation.
  2. Invoke the card capture form, sending the uniqueId field within the metadata object of the customer as described in the Customer Information section.

Creating a Basic Purchase

Send the newly obtained token from the browser or mobile app to the application server to create the purchase transaction.

From the server, invoke the Create a Purchase method, including the Purchase object with the token and additional transaction details.
If operating with a previously created customer and a saved card through the card capture form or direct tokenization, invoke the Get Customer function and obtain the CommerceToken of the selected card, detailed within the PaymentProfile object. Then, send the purchase with the obtained value.

CommerceToken Format
Format"Token": "CT__{{string}}"
Example"Token": "CT__wZcNQkcZtnYWeHIgR2vgWUUliS3lR18E4jiYpVJ8QQQ_",

Example Response - GetCustomer for a customer with a Saved Card

{
    "Response": {
      "CustomerId": 53479,
      "Created": "2021-04-06T16:08:43.767",
      "CommerceCustomerId": null,
      "Owner": "Commerce",
      "Email": "Email222222@mail.com",
      "Enabled": true,
      "ShippingAddress": null,
      "BillingAddress": {
        "AddressId": 51615,
        "AddressType": 1,
        "Country": "UY",
        "State": "Montevideo",
        "AddressDetail": "10000",
        "PostalCode": null,
        "City": "MONTEVIDEO"
      },
      "Plans": null,
      "AdditionalData": null,
      "PaymentProfiles": [
        {
          "PaymentProfileId": 55591,
          "PaymentMediaId": 2,
          "Created": "2021-04-19T11:26:17.693",
          "LastUpdate": null,
          "Brand": "MasterCard",
          "CardOwner": "John Simpson",
          "Bin": null,
          "IssuerBank": "Santander",
          "Installments": "1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23;24",
          "Type": "CreditCard",
          "Token": "CT__wZcNQkcZtnYWeHIgR2vgWUUliS3lR18E4jiYpVJ8SzQ_",
          "Expiration": "202211",
          "Last4": "0001",
          "Enabled": true
        }
      ],
      "CaptureURL": "https://testapi.BambooPayment.com/v1/Capture/",
      "UniqueID": "UI_263b2dde-b151-4f09-b8bf-c65883d2cb3b",
      "URL": "https://testapi.BambooPayment.com/v1/api/Customer/53479",
      "FirstName": "FistName 2222",
      "LastName": "LastName 2222",
      "DocNumber": "12345672",
      "DocumentTypeId": 2,
      "PhoneNumber": "24022330"
    },
    "Errors": []
  }

Request Example for purchase with CommerceToken

{
    "TrxToken": "CT_kYv0qTHckRiZ4wjCz5NguZRuwFLSIrQc4jiYpVJ8SzQ_",
    "Order": "17030613595101621fb",
    "Amount": 123456,
    "Currency": "USD",
    "Capture": true,
    "TargetCountryISO":"CL"
  }

One-Click Recurring Purchases

Once customers are successfully registered, some cards allow certain transactions without requiring a Verification Code (CVV), enabling a smoother user experience (one-click payments).

The Verification Code must be requested whenever transactions are made with cards that do not allow this feature, as it cannot be stored on our servers.

To invoke the Verification Code, follow the steps described in this section.

footer
Last modified February 24, 2025

© Bamboo | All rights reserved 2025