Skip to content

Payment Collector

This guide describes how to retrieve, manage, and tokenize user payment methods using the Glofox API. It outlines the steps for accessing stored credit cards (cards), bank debit payment mandates (mandates), and payment history. It also explains how to initiate the payment collector flow, which securely allows users to add new payment methods.

The payment collector is implemented through a secure iFrame that handles card and mandate entry, validation, and tokenization. This ensures that sensitive payment information is never handled directly by your application and remains fully PCI‑compliant.

Payment collector

Access the Payments section on API reference for comprehensive details on retrieving the payment methods available to a user.

GET credit card (card)

Retrieve the credit card associated with a specific user.

  • Endpoint: /2.1/branches/{{x-glofox-branch-id}}/users/{{sample-user-id}}/cards
  • Method: GET
  • Content-Type: application/json

Required Headers

{
  "x-glofox-branch-id": "{branch_id}",
  "x-api-key": "{api_key}",
  "x-glofox-api-token": "{api_token}"
}

GET debit (mandates)

Retrieve the bank debit mandate(s) for a specific user (mandates).

  • Endpoint: /2.1/branches/{{x-glofox-branch-id}}/users/{{sample-user-id}}/mandates
  • Method: GET
  • Content-Type: application/json

Required Headers

{
  "x-glofox-branch-id": "{branch_id}",
  "x-api-key": "{api_key}",
  "x-glofox-api-token": "{api_token}"
}

GET payment history

Retrieve a user's payment history.

  • Endpoint: /2.0/charges?user_id={{sample-user-id}}&page=1&sort_by=-created&include=model&across_branches=true&limit=100
  • Method: GET
  • Content-Type: application/json

Required Headers

{
  "x-glofox-branch-id": "{branch_id}",
  "x-api-key": "{api_key}",
  "x-glofox-api-token": "{api_token}"
}

Each user is permitted to have only one payment method per type. For example, a user may register a single credit card and a single debit card concurrently.

Payments Collector

The payments collector should be implemented according to the workflow outlined in the following steps.

Step 1

Invoke the payment collector endpoint to retrieve the payment collector iFrame URL. This URL is provided in the response from the payment-methods endpoint.

  • Endpoint: /2.1/branches/{branch_id}/payment-methods?includes=provider,iframe
  • Method: GET
  • Content-Type: application/json

Required Headers

{
  "x-glofox-branch-id": "{branch_id}",
  "x-api-key": "{api_key}",
  "x-glofox-api-token": "{api_token}"
}

Example Response

{
  "data": [
    {
      "_id": "5bcf7347250c89a421d4561e",
      "branch_id": "570b795c778f3bbd138b4568",
      "active": true,
      "staff_only": false,
      "type_id": "CARD",
      "account_management_link": null,
      "same_card_and_dd": false,
      "provider": {
        "id": "5f4758e8af36710a928afc4b",
        "name": "STRIPE_CUSTOM_EU",
        "charge_percentage": 5,
        "is_charge_percentage_editable": true,
        "fixed_charge": 1,
        "is_fixed_charge_editable": true,
        "publishable_key": "pk_test_1loGihTKRmyb83crV9eKxhsv",
        "account_id": "3",
        "tokenization_handler": "STRIPE",
        "gateway_migration_state": null,
        "features": []
      },
      "iframe": {
        "parameters": {
          "color_accent": null,
          "color_background": null,
          "color_text": null
        },
        "domain": "https://development.glofox.com",
        "full_path": "/payment-collector/#/branch/570b795c778f3bbd138b4568/tokenizationMethod/stripe/tokenizationKey/pk_test_1loGihTKRmyb83crV9eKxhsv/payment-collector?colors[background]=FFFFFF&colors[accent]=000000&colors[text]=508B4B&transparent_background=0&user[id]=5b9a8224953e0d018e357a32&user[first_name]=Eduardo&user[last_name]=Doe&user[phone]=696966969&user[email]=test@test.com&user[country]=IRL&user[currency]=EUR&branch[name]=Cookie%2BStudio&branch[address]=Alameda%2Bdel%2Bcorregidor%2B550%2Bdpto%2BA&branch[city]=Lima&branch[postal]=15024&branch[state]=Lima&branch[country]=IE&branch[phone]=089951436&branch[email]=n.nambiar%2540glofox.com&branch[id]=570b795c778f3bbd138b4568&account_id=3"
      }
    }
  ]
}

Step 2

Render an iFrame using the URL obtained in the previous step. Construct the iFrame URL by concatenating data[i].iframe.domain with data[i].iframe.full_path. Issuing a GET request to this constructed iFrame URL will load the card collector interface, enabling users to enter card or mandate details. Upon successful entry and validation of these details, the tokenization process will be initiated.

Step 3

Monitor the completion of the tokenization process and retrieve the resulting token by using the postMessage API. Attach an onload handler to the payment collector iframe, send a registration message to register the parent window for tokenization callbacks, and then listen for message events to receive the token.

Using postMessage Listener

Once the iframe loads, register for tokenization callbacks and listen for message events to capture the token.

Web application integration example

The container page must be hosted on an authorized domain. For local development, the following URLs are pre-authorized: http://localhost, http://localhost:8080.The example below demonstrates how to add an onload event handler to the payment collector iFrame, register the parent window for tokenization callbacks, and listen for messages containing the token:

<iframe id="paymentCollectorIframe"
        src="IFRAME_URL_FROM_PAYMENT_METHODS_ENDPOINT"
        onload="setupIframeCommunication()"
        style="width: 500px; height: 700px;"
        frameborder="0">
</iframe>

<script>
    // Establish communication with the iFrame after it has loaded
    function setupIframeCommunication() {
        const iframe = document.getElementById('paymentCollectorIframe');
        const targetOrigin = data[i].iframe.domain; // The iFrame's domain

        // Register the parent window for callbacks using postMessage
        // Consider using a timer or interval to ensure the iFrame is fully loaded
        iframe.contentWindow.postMessage('register parent', targetOrigin);

        // Listen for messages from the iFrame
        window.addEventListener('message', function(event) {
            // Validate the message origin
            if (event.origin === targetOrigin) {
                console.log('Message received from iframe:', event.data);
                // Handle the token and options received from the iFrame here
            }
        }, false);
    }
</script>

Replace IFRAME_URL_FROM_PAYMENT_METHODS_ENDPOINT with the actual iFrame URL obtained from the payment-methods endpoint.

This example illustrates the essential steps for implementing iFrame communication in web applications, ensuring secure and dynamic interaction with the payment collector.

Important

To utilize the payment collector, your domain must be authorized.
This authorization is currently handled by our internal team.
Please reach out to us to request domain authorization sending an email to Glofox.APISupport@abcfitness.com

Step 4

Submit the token and options to the appropriate endpoint to save the new card or mandate. Once the token and options are obtained, send them to the relevant endpoint in the Glofox API to register the new payment method.

Cards Endpoint

  • Endpoint: /2.1/branches/{branch_id}/users/{user_id}/cards
  • Method: POST
  • Content-Type: application/json

Required Headers

{
  "x-glofox-branch-id": "{branch_id}",
  "x-api-key": "{api_key}",
  "x-glofox-api-token": "{api_token}"
}

Request Body

{
  "card_token": "string",
  "options": {}
}

Mandates Endpoint

  • Endpoint: /2.1/branches/{branch_id}/users/{user_id}/mandates
  • Method: POST
  • Content-Type: application/json

Required Headers

{
  "x-glofox-branch-id": "{branch_id}",
  "x-api-key": "{api_key}",
  "x-glofox-api-token": "{api_token}"
}

Request Body

{
  "mandate_token": "string",
  "options": {}
}