Recurring Use Token

The customer will receive a CommerceToken after registering their card, which they can use 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 so, you must invoke a POST request to the following URLs according to your needs.

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

Request parameters

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 recently created customer’s information or the error that may have occurred. In the Response.CustomerId, you can find the customer id generated by the API to allow you to consult or update a customer.

Use the following parameters to perform extra operations over customers:

• CaptureURL: Card data capture URL. Open this URL in an iframe to start capturing sensitive data. For more information, refer to Invoking the Card Enrollment.
• UniqueID: Temporary unique identifier used to register external payment methods. Every time you request the Customer information, you get a new identifier. For more information, refer to Invoking the Card Enrollment.
• URL: URL when you can consult the information of a client. For more information, refer to 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 you have created a user, you can perform operations to get or update a customer’s information.

Get a customer

You can get a customer’s information using their Id or email address.

To do so, you must invoke a GET request to the following URLs according to your needs.

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

In response, you will get a list with the same object returned when creating a customer. Example:

{
    "Response": [
        {
            "CustomerId": 249205,
            "Created": "2023-08-22T14: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_61109a7f-5414-4424-8654-18c30060cd2b",
            "URL": "https://api.stage.bamboopayment.com/api/Customer/249205",
            "FirstName": "Kristel",
            "LastName": "Yoder",
            "DocNumber": "31130749",
            "DocumentTypeId": 2,
            "PhoneNumber": "093000000",
            "ExternalValue": null
        }
    ],
    "Errors": []
}

Update a customer

To update the information of a customer, you must invoke a POST request to the following URLs according to your needs.

• 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 you created the user. Include in the body, the parameters you want to update for the user.

As response, you will get the same object returned when creating a customer.

Capture the Card Data

The next step is to get the token of the customer’s card. To do so, you can invoke the Card Enrollment or use Direct tokenization if your commerce is PCI-compliant.

Invoking the Card Enrollment

The following sequence diagram explains the Card Enrollment flow.

API calls during flow:

• 3 HTTP/GET (server to server): {environment_api}/v1/api/customer/{customer-id}
• 11 HTTP/GET (server to server): {environment_api}/v1/api/customer/{customer-id}

With the information obtained in the previous step, you can invoke the OpenIframeCustom or OpenIframeCustomWithPaymentMediaOptions methods (see details below) from the JavaScript library PWCheckout, which will manage the card data capture.

OpenIframeCustom

The OpenIframeCustom method receives two parameters:

• URL: The URL specifies the iFrame window address where customers enter Card data.
  The URL is created by concatenating the received data as follows: {CaptureURL}?key={publicKey}&session_id={UniqueID} where {CaptureURL} represents the base URL + /Capture. For example https://api.stage.bamboopayment.com/v1/Capture.
  You can found this information in the CaptureURL parameter in the response.
• UniqueID: an identifier to distinguish the data capture session.
  You can found this information in the UniqueID parameter in the response.

<script type="text/javascript">
        PWCheckout.OpenIframeCustom(url, UniqueID);
</script>

OpenIframeCustomWithPaymentMediaOptions

The OpenIframeCustomWithPaymentMediaOptions method receives four parameters:

• URL: The same as OpenIframeCustom.
• UniqueID: The same as OpenIframeCustom.
• PaymentMediaid: Identifier of the Payment method. If set, the Card Capture Form will only accept cards of this Payment Media. This parameter applies only to Uruguay.
• BankId: Bank identifier. This parameter applies only to Uruguay.

The Card Capture Form will only accept cards of the specified Payment Method and Bank if you set both parameters, but they are optional.

Call examples of the OpenIframeCustomWithPaymentMediaOptions method:

1. Call with PaymentMediaId and BankId set:

<script type="text/javascript">
      PWCheckout.Iframe.OpenIframeCustomWithPaymentMediaOptions(url, UniqueID, paymentMediaId,bankId);
</script>

2. Call with BankId set and PaymentMediaId in null.

<script type="text/javascript">
      PWCheckout.Iframe.OpenIframeCustomWithPaymentMediaOptions(url, UniqueID, null, null);
</script>

The customer enters the card data and after confirming, the PWCheckout library receives the notification that the card was captured correctly.

The merchant page can subscribe to the tokenCreated event that will be triggered upon receiving notification that the card data was captured.

The page can also set the property form_id (using the SetProperties method) to indicate the identifier of a form on the page that will be controlled by the PWCheckout library. The library will submit the form once the card information has been captured.

In response to the notification received (by the JavaScript event or by the form submit), the merchant page must re-request the updated Customer information by making the following HTTP/GET call (server to server): {environment_api}/v1/api/customer/{customer-id}.

The returned Customer object contains the PaymentProfiles of the customer. These objects have information on the payment methods associated with the client, where in the Token field, CommerceToken generated represents the payment card.

Response example that includes a PaymentProfile:

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

Using Direct tokenization

Since the user is registered in your commerce, you must invoke the method to create the token for registered users.

Create a Basic Purchase

The token just obtained must be sent from the browser or the mobile app to the application server to create the purchase transaction.

From the server, invoke the Create a Purchase, including the Purchase object with the token and other transaction data.

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

The PaymentMediaId and TrxToken fields are optional, but sending one is mandatory, depending on the flow you want to use.

• PaymentMediaId: Alternative payment method identifier (transfer, cash, and processing that requires customer redirection). You can obtain this identifier by consulting the Payment Methods by country section.

• TrxToken: You can generate the token and transact by sending it in this field.

Recurring Purchases in One Click

After customers register correctly, some cards allow certain transactions without needing a Verification Code (CVV), which allows a more agile user experience (payments in one click). In these cases, purchases can be sent directly without requesting more information from the customer, as explained in the previous point, Basic purchase.

You must request the Verification Code every time for transactions where the card does not support this feature, as we cannot store it on our servers.

Verification Code Request Flow

For the Payment Cards that require the entry of the Verification Code in all transactions, we designed the following workflow:

1. The customer, identified correctly on the Commerce website, initiates the payment process of a purchase using a card previously registered and associated with their account.

2. The merchant page submits the data to the web server to prepare the information sent to Bamboo Payment.

3. The merchant’s Web Server sends the purchase through the BambooPayment API, identifying the CommerceToken as the Payment Method the customer selects.

4. We carry out a series of validations; in this case, we verify if the payment method chosen allows the execution of transactions without the Verification Code. The selected Payment method does not support this functionality in this flow, so the transaction can only be completed once the Card Verification Code has been obtained.

5. We return the Purchase object in Pending status as a response, indicating that some action is needed to complete the process. The Purchase object returned will also contain the CommerceAction object that describes the necessary steps to be performed by the merchant.

The merchant must store the pending purchase information (at least the PurchaseId for future validations) and process the CommerceAction information to determine the required action. Take into consideration the following properties in this scenario:

• ActionReason: Will have the value VERIFICATION_CODE_NEEDED because the purchase requires this Verification Code.
• ActionType: This field will have the value 2 corresponding to the action PWCapture, a function of the javascript component PWCheckout that allows to process this type of actions.
• ActionURL: This field specifies the URL that you must send as parameter to the PWCapture method of the PWCheckout component.

6. The merchant’s web page must show the Verification Code request form to the client using the PWCapture method as shown here:

<script type="text/javascript">
  PWCheckout.PWCapture(url);
</script>

Where the value of the url parameter corresponds to the ActionURL field of the received CommerceAction object.

7. The customer will see the iframe with the Capture Form, which in this case will be presented showing the masked card number (only the last four digits) and a text field for the entry of the Verification Code.

8. The customer enters the Verification Code of the card used to create the purchase.

9. The verification code the customer enters is sent directly to the Bamboo Payment servers, where it’s used to create the authorization message.

10. Bamboo Payment sends the authorization message to the corresponding acquirer with the complete data.

11. Bamboo Payment processes the acquirer’s response and updates the purchase status according to this response.

12. Bamboo Payment generates a notification to the merchant, informing the Purchase object and its final status determined by the authorization process. The Purchase sent is the same previously answered in step 5, the merchant should validate the information received (at least the PurchaseId matches the expected one). This notification is sent to the WebHook service the merchant must implement to obtain the different notifications generated by Bamboo Payment.

Notification Alternative

In addition to the option to receive a notification from Bamboo Payment at the end of the purchase process (step 12 of the normal flow), an alternative flow can be executed to explicitly query the result of the purchase once it is detected that the pending process has finished (after step 5).

This flow uses the functionalities implemented in the PWCheckout JavaScript library to inform the completion of the pending purchase process.

The steps related to this flow are listed below and explained; the initial stages before 12 are the same as those previously described.

12. Once the pending process has finished, the PWCheckout library receives a notification of the status of the process.

13. The PWCheckout library triggers the notificationReceived event. The merchant must subscribe previously to the event through the Bind method in the following way:

<script type="text/javascript"> 
  PWCheckout.Bind("notificationReceived", NotificationHandler);
</script>

The merchant must implement the NotificationHandler function (the name is just an example), which will receive information about the final state of the process.

Example of the function for handling notifications:

<script type="text/javascript">
    function NotificationHandler(notification) {
        if (notification.ProcessStatus == 1) {
            //Process OK
        } else {
            //Process with errors
        }
    }
</script>

The ProcessStatus field of the received notification will determine the final state of the process. The possible values are:

• OK (value 1) – The process finished successfully.
• Pending (value 2) – The process is still pending.
• Error (value 3) – The process ended in error.

14. After the web page receives the notificationReceived event, it may continue with the flow.

15. The merchant must invoke a GET call from the web server to the BambooPayment Purchase API, querying the PurchaseId previously stored in step 5.

For this, the call is made: HTTP/GET (server to server):

{environment_api}/v1/api/purchase/{purchase-id}

16. The Bamboo Payment response will contain the Purchase object with a status other than Pending (depending on the result of the transaction), so it can be processed as a regular purchase response.

For this, the call is made: HTTP/POST (server to server):

{environment_api}/v1/api/purchase

Last modified December 20, 2024

© Bamboo | All rights reserved 2024