Recurring Use Token
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.
Attention
The Customer Management functionality is now available in version V3 of the API, but some operations remain under V1.
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
Parameter | Type | Mandatory? | Description |
---|---|---|---|
Email | string | Yes | Customer email address. |
FirstName | string | Yes | Customer name. |
LastName | string | Yes | Customer last name. |
DocumentTypeId | string | Yes | Customer document type. Find for the Legacy version, the possible values in the Document types table according to the country. |
DocNumber | string | Yes | Customer document Number. |
Owner | string | No | It determines whether the user is anonymous or if the merchant, or us, registered it. The possible values are:
|
PhoneNumber | string | Yes | Customer contact telephone number. |
BillingAddress | object | Yes | This parameter is the customer’s billing address. |
BillingAddress →AddressID | integer | Yes | Address Identifier. |
BillingAddress →AddressType | string | Yes | Type of address. |
BillingAddress →Country | string | Yes | Country of the address. |
BillingAddress →State | string | Yes | State of the address. |
BillingAddress →City | string | Yes | City of the address. |
BillingAddress →AddressDetail | string | Yes | This 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:
- Obtain the customer’s uniqueId by executing the Get Customer operation.
- Invoke the card capture form, sending the
uniqueId
field within themetadata
object of thecustomer
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.
