Recurring Use Token

Unlike Anonymous Users, these users are registered on the website, allowing you to identify them and associate their card information for subsequent purchases without re-entering the details.

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/v3/api/customer
Stage: https://api.stage.bamboopayment.com/v3/api/customer

Request Parameters

Parameter	Type	Mandatory?	Description
`Email`	`string`	Yes	Customer’s email address.
`FirstName`	`string`	Yes	Customer’s first name.
`LastName`	`string`	Yes	Customer’s last name.
`DocumentType`	`string`	Yes	Customer’s document type. Find possible values in the Document Types table based on the country.
`DocumentNumber`	`string`	Yes	Customer’s document number.
`Owner`	`string`	No	Indicates whether the user is anonymous or if the merchant or we registered them. Possible values: Our Commerce. This is the default value. Anonymous
`PhoneNumber`	`string`	Yes	Customer’s contact phone number.
`Address`	`object`	Yes	This parameter is the customer’s billing address.
`Address`→`AddressType`	`string`	Yes	Type of address.
`Address`→`Country`	`string`	Yes	Country of the address.
`Address`→`State`	`string`	Yes	State of the address.
`Address`→`City`	`string`	Yes	City of the address.
`Address`→`AddressDetail`	`string`	Yes	Additional address information, such as street, number, etc.

Request Example

{
    "Email": "test@bamboopayment.com",
    "FirstName": "Jhon",
    "LastName": "Doe",
    "DocumentNumber":"123456721",
    "DocumentType": "DNI.AR",
    "PhoneNumber" : "549112345678",
    "Address": {
        "Country": "ARG",
        "State": "Buenos Aires",
        "City": "Buenos Aires",
        "AddressDetail": "Solano Lopez 1774"
    }
}

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",
        "Owner": "Commerce",
        "Email": "kristeldyoder@teleworm.us",
        "Enabled": true,
        "Address": {
            "Country": "Uruguay",
            "State": "Montevideo",
            "AddressDetail": "100",
            "PostalCode": "11600",
            "City": "Montevideo"
        },
        "PaymentProfiles": [],
        "UniqueID": "UI_b53cb8db-771e-4622-a5db-0e58e156f192",
        "URL": "https://api.stage.bamboopayment.com/api/Customer/249205",
        "FirstName": "Kristel",
        "LastName": "Yoder",
        "DocNumber": "31130749",
        "DocumentType": "CI.UY",
        "PhoneNumber": "093000000",
    }
}

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/v3/api/customer
Stage: https://api.stage.bamboopayment.com/v3/api/customer

	Endpoint
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.

Alert

The Update customer operation has not yet been migrated to version 3 of the API.

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.

Info

If using an alternative payment method identifier, this step is not required, and you should include PaymentMethod.

Invoking the Card Enrollment Form

Info

If using the Legacy version of the card capture form, refer to the steps here.

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

Obtain the customer’s uniqueId by executing the Get Customer operation.
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.

Example of a Customer with a Saved Card Response

{
    "CustomerId": 415589,
    "CommerceId": 0,
    "CommerceAccountId": 4924,
    "Email": "test@bamboopayment.com",
    "FirstName": "Jhon",
    "LastName": "Doe",
    "ExternalCustomerId": null,
    "PhoneNumber": "549112345678",
    "BornPlace": null,
    "BornDate": null,
    "IsAnonymous": false,
    "Created": "0001-01-01T00:00:00.000",
    "Document": {
        "DocumentType": "DNI.AR",
        "Value": "123456721",
        "Abbreviation": null,
        "Description": null
    },
    "Country": "AR",
    "Gender": null,
    "Address": {
        "Country": "ARG",
        "State": "Buenos Aires",
        "City": "Buenos Aires",
        "AddressDetail": "Solano Lopez 1774"
    },
    "SessionId": "UI_d657da45-d67a-46d4-a53b-22deb5e05691",
    "PaymentProfiles": [
    {
        "PaymentProfileId": 435168,
        "PaymentMediaId": 1,
        "Created": "2025-01-16T18:26:30.753",
        "LastUpdate": "2025-01-16T18:26:30.753",
        "Brand": "VISA",
        "CardOwner": "Sora Doe",
        "Bin": "463403",
        "IssuerBank": "Santander",
        "Installments": null,
        "Type": "CreditCard",
        "IdCommerceToken": 53963,
        "Token": "CT__gIOtp4dvXEiWnsxmFtHWTSSDAQ",
        "Expiration": "202704",
        "Last4": "1111",
        "Enabled": true,
        "DocumentNumber": "",
        "DocumentTypeId": 2,
        "ExternalValue": null,
        "AffinityGroup": null
    }
    ]
}

Request Example

{
    "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).
In these cases, purchases can be submitted directly without requesting additional customer information, as explained in the previous section, Basic Purchase.

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.

Last modified January 20, 2025