Building blocks for group payments

Pay By Group makes it easy to accept payment from a group of customers online - in your app or on your site. Get integrated quickly by reviewing the Sample Scenarios, and select from our range of API (back-end) and JavasScript Library (front-end) integration tools.

Get Started    
Suggest Edits

API overview

 

Our REST API can be used for everything from the most simple implementation to the most complex use cases you may want to create. All endpoints are described in detail in the API Reference. Our Sample Scenarios walk you through which endpoints you will need for standard use cases.

Most endpoints accept JSON format, except for the ones that involve uploading files, those are handled with www-form/multipart format. All endpoints however respond with JSON.

All of the endpoints require authentication, which is handled through JWT, and the token is sent in the Authorization header. See Authentication for more details.

Suggest Edits

Authentication

 

All of the endpoints in the HTTP API use HTTP Basic Auth. Use your API Access Key as your username. Use your API Secret Key as your password to authenticate. The username:password should then be encoded with Base64 to generate the string for the Basic Authorization.

For example where username is Aladdin and password is OpenSesame:

GET /purchases/:id
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Use Base64 Encoding

For Basic authorization, you should be encoding the username and password as a Base64 string. For more information on this process, see Section 10.1 here, and see how to do the encoding with the btoa method in Javascript here.

 

Every merchant account gets a separate test environment account for testing. Requests made with test credentials never trigger real transactions but otherwise behave the same as the production environment.

Access and Credentials

To access the test, aka "sandbox" version of your Business Portal

  1. As an Administrator in your production account, click on the "Integration" link on the left-hand side in your Business Portal, then scroll to the bottom and click "Login" under the "Sandbox Environment" section header.
  2. Once inside your Sandbox Business Portal, you may click "Users" on the left-hand side and grant others in your company access to your Sandbox environment. (Note: you must invite users to your production and sandbox environment separately. Adding users in one environment does not automatically add them in the other, with the exception of the original administrator for your production account.)

To obtain the test version of your API Secret Key and API Access Key, click "Integation" on the left-hand side once you are in your Sandbox Business Portal.

Test Card Numbers

If you are using a 3rd party payment gateway to receive payments, then use these cards for testing in the sandbox environment.

Card Type
Good Card
Declined/Failed Card

Visa

4111111111111111

4012888888881881

Mastercard

5555555555554444

5105105105105100

American Express

378282246310005

371449635398431

Discover

6011111111111117

6011000990139424

If you are using bank account payouts with Pay By Group as your processor to receive payments, then use these cards for testing in the sandbox environment.

Card Type
Good Card
Declined/Failed Card

Visa

4242424242424242

4000000000000002

Mastercard

5555555555554444

American Express

378282246310005

Discover

6011111111111117

JS SDK Testing

To use the sandbox environment with your JS SDK, include our library with these PBGConfig.apiURL and PBGConfig.consumerPortalURL values and using your sandbox apiAccessKey

<script>
  (function () {
      // add a queue event here
      PBGConfig = window.PBGConfig || (window.PBGConfig = {});
      PBGConfig.apiURL = 'https://api-test.paybygroup.com';
      PBGConfig.consumerPortalURL = 'https://go-test.paybygroup.com';
      PBGConfig.className = 'pbg-button';
      var s = document.createElement('script');
      s.id = 'pbg_script'
      s.type = 'text/javascript';
      s.async = true;
      s.dataset.apiAccessKey = YOUR_PBG_SANDBOX_API_ACCESS_KEY;
      s.src = 'https://integrate.paybygroup.com/paybygroup.sdk.latest.min.js';
      var x = document.getElementsByTagName('script')[0];
      x.parentNode.insertBefore(s, x);
    })();
</script>

Webhooks Testing

Please send us the webook_listener_url you wish to use for your sandbox environment to add to your account.

All sandbox webhooks will be sent there, and they will be signed using your sandbox API Secret Key.

Suggest Edits

Using the JS SDK

 

With the Pay By Group JS SDK loaded, you can create purchases easily by adding an HTML element with the class pbg_button and access Pay By Group's full API functionality through the front-end.

You can create a split-the-cost checkout option as easily as this:

<div
     class="pbg-button"
     data-payload='{"product":{"name":"Trip to Vegas","costType":"total","costs":[{"amount":{"amountCents":100000,"currencyCode":"USD"}}]},"payments":[{"percentage":100}]}' 
/>

Before calling these methods, you need to include our library into your site.

<script>
  (function () {
      // add a queue event here
      PBGConfig = window.PBGConfig || (window.PBGConfig = {});
      PBGConfig.className = 'pbg-button';
      var s = document.createElement('script');
      s.id = 'pbg_script'
      s.type = 'text/javascript';
      s.async = true;
      s.dataset.apiAccessKey = YOUR_PBG_API_ACCESS_KEY;
      s.src = 'https://integrate.paybygroup.com/paybygroup.sdk.latest.min.js';
      var x = document.getElementsByTagName('script')[0];
      x.parentNode.insertBefore(s, x);
    })();
</script>

The parameter passed to the script initialization s.dataset.apiAccessKey can be found by logging into your Business Portal.

Browser support

For security reasons, the JavaScript Library will not work on browsers with no TLS 1.1 support (e.g. Chrome < 22, Android browser < 5, Firefox < 27, IE < 11, Safari < 7)

Suggest Edits

Display checkout button

 

You can create a split-the-cost checkout button very easily. You only need to make sure the Pay By Group JS library is included on the page and then add the following:

Create button placeholder(s).

<div
     class="pbg-button"
     data-payload='{"group":
                     {"organizerEmail":"user@example.com",
                     "organizerName":"John Doe"},
                    "product":
                     {"name":"Trip to Vegas",
                     "description":"Product description",
                     "costType":"total",
                     "costs":[{"amount": {"amountCents":100000,
                       "currencyCode":"USD"},
                       "minSlots":1,
                       "maxSlots":100}]},
                     "payments":[{"percentage":100,
                       "dueDeadline":"2019-11-23T04:26:19",
                       "dueDeadlineTimeZone": "America/Los_Angeles"}]}' />

When the JS SDK is loaded, a click handler will be bound to each HTML element that has the class pbg-button. You can define the class name to use by setting a value to PBGConfig.className.

The payload data attribute of the placeholder holds the stringified version of a purchase valid JSON object and it has the same attributes and structure as described in Create purchase endpoint.

Ensure valid JSON and HTML with these rules for characters inside parameter values

  1. Replace ' with the HTML entity &apos; or &#39; to avoid breaking the HTML code
  2. Escape " by using \" to avoid breaking the JSON code

This is needed most commonly for the name, description, and organizer_name parameters values.

Pre-fill the claim form

Additionally you can include the claimFormFields object in the element payload to auto-populate the Claim form that the JS SDK triggers in a modal on click.

The parameters accepted by the claim form almost precisely mirror those of the Claim Purchase method and are:

Attribute
Type
Always present
description

invitees

Array

no

Array of invitees that will pre-populate the invitation list

˲ email

String

no

The email of the invitee

˲ fullName

String

no

The full name of the invitee

˲ allowedShareAmount

Object

no

Only relevant when organizer chooses the custom splitType

˲˲ amountCents

Number

yes

The amount in cents of the invitee's recommended share

˲˲ currencyCode

String

yes

The three letter currency code, which must match the currency of the purchase

message

String

no

Populates the message that will be sent to the invitees, which the organizer can edit or remove

splitType

String

no

Pre-selects the how-to-split dropdown value and is only relevant when your product costType is total and must be either even_split or specified_per_person (details)

minSlots

Integer (int32)

no

Pre-populates the # of ways to split when "Evenly" (even_split) is selected in the how-to-split dropdown

minContribution

Object

no

Pre-populates the minimum required contribution when "Custom" (specified_per_person) is selected in the how-to-split dropdown

˲ amountCents

Number

yes

The amount in cents of the minimum required contribution

˲ currencyCode

String

yes

The three letter currency code, which must match the currency of the purchase

Example with claim form values:

<div
     class="pbg-button"
     data-payload='{"group":
                     {"organizerEmail":"user@example.com",
                     "organizerName":"John Doe"},
                    "product":
                     {"name":"Trip to Vegas",
                     "description":"Product description",
                     "costType":"total",
                     "costs":[{"amount": {"amountCents":100000,
                       "currencyCode":"USD"},
                       "minSlots":1,
                       "maxSlots":100}]},
                     "payments":[{"percentage":100,
                       "dueDeadline":"2019-11-23T04:26:19",
                       "dueDeadlineTimeZone": "America/Los_Angeles"}],
                      "claimFormFields": {
                        "message": "Lorem ipsum dolor sit amet",
                        "invitees": [
                          {
                            "email": "example@paybygroup.com",
                            "fullName": "Example Name",
                            "allowedShareAmount": {
                              "amountCents": 10000,
                              "currencyCode": "USD"
                            }
                          },
                          {
                            "email": "example1@paybygroup.com",
                            "fullName": "Example One",
                            "allowedShareAmount": {
                              "amountCents": 20000,
                              "currencyCode": "USD"
                            }
                          }
                        ]
                      }
                    }' 
/>

Manual triggers

You can also manually trigger a placement if you add placeholders dynamically (e.g. when inserting placeholders using AJAX).

To manually trigger the button placement, call this method:

PayByGroup.bindButtonHandler();

If you don’t pass any parameter, it will replace each placeholder in the page. If you want to insert only one button, then pass it as the argument of the method:

var myButton = document.getElementById('my-dynamic-button');
PayByGroup.bindButtonHandler(myButton);

This will generate the following button at the placement(s) you specify. You can override the class styling to use your own graphics as you like.

Clicks on the button will present an overlaid iframe on your site for the customer to create their group purchase. If they cancel the creation process, they will remain on the current page of your site. If they complete it, they will be redirected to their group dashboard hosted by Pay By Group.

If you want to use your own styling

Just add a child element to the placeholder and that will override the default button.

<div class="pbg-button" data-payload="...">
  <div class="button btn-primary">Custom Checkout Button</div>
</div>

Must include text inside div

If you do not include text inside the div, you must use &nbsp; to add a blank text node inside the div so that it is not treated as empty.

Suggest Edits

Create a purchase

 

You can create purchases with the createPurchase method.

var attributes = {
  group: {
    organizerEmail: 'user@example.com',
    organizerName: 'John Doe',
  },
  product: {
    name: 'Trip to Vegas',
    description: 'Product description',
    costType: 'total',
    costs: [
      {
        amount: {
          amountCents: 100000,
          currencyCode: 'USD',
        },
        minSlots: 2,
        maxSlots: 8,
      },
    ],
  },
  payments: [
    {
      percentage: 100,
      dueDeadline: new Date().toISOString(),
    },
  ],
}

PayByGroup.Purchase.create(attributes);

As you can see, the purchase object you pass to the Purchase.create method has the same attribute structure described in the Create purchase endpoint.

This method executes an asynchronous request and returns a Promise, to handle the response, you can register a success handler in a then callback or an error handler in a catch callback.

PayByGroup.Purchase.create(attributes)
  .then((purchaseObject) => {
    console.log(purchaseObject.data);
    // Do something on success
  })
  .catch((err) => {
    // Do something with the error
  });
Suggest Edits

Pull purchase information

 

Whenever you want to show information about a purchase embedded in your site, you can get the data for the purchase by calling Purchase.find method using the Pay By Group ID of the purchase as the only parameter.

PayByGroup.Purchase.find('a94nf93')
  .then((purchaseObject) => {
    console.log(purchaseObject.data) // Purchase Object
    console.log(purchaseObject.url()) // https://go.paybygroup.com/purchases/a94nf93
  });

The purchase passed in the Promise callback is an object with the same structure defined here.

You can set up a URL endpoint to receive a series of webhooks because various aspects of the Pay By Group process are asynchronous, and we need to notify you when certain processes succeed or fail.

Note

Webhooks are delivered over HTTPS. You should ensure your server is correctly configured to support HTTPS with a valid server certificate.

When specific events occur, Pay By Group generates an Event object, such as this:

{
  "type": "purchase_claimed",
  "api_version": "1",
  "published_at": "2018-10-22T12:34:56Z",
  "error": null,
  "data": {
    "purchase_id": "b729-a343-4b48-8ea0",
  }
}

An Event object is described by the following attributes:

Attribute
Type
Always present
Description

type

String

yes

The type of event generated

api_version

String

yes

The version of the API you’re using

error

String

no

If the event is a failure event, then the error will include a human-readable description of what happened and/or the steps to resolve it

data

Object

yes

Event payload hash, contents depends on the type value.

Response status

If your server doesn’t respond with a success status (any 2xx), we will keep retrying the webhook up to 10 times. Once the max limit is reached, we’ll stop retrying.

Headers

Each webhook request includes a set of headers that contain useful information.

Header
Description

X-Event-ID

A unique id for this event, you should log this ID to make sure you don’t process an event more than once

X-PBG-Signature

HMAC hex digest of the payload, using the secret key assigned to your merchant account (see Security section below)

Security

Theoretically, anoyone can post HTTPS payload to your webhook endpoint. Therefore, it is strongly recommended for you to implement a security/validation check to ensure that webhook events originate from Pay By Group.

To do that, all Pay By Group webhook events contain a unique signature. Your application can optionally verify the authenticity of this signature using these steps:

  1. Receive the signature token included in the X-PBG-Signature header.
  2. Hash the webhook payload using HMAC and your secret key assigned to your merchant (you can see this key in the Business Portal under the Integration section).
  3. Compare the two signatures. If they are the same, then the webhook is authentic.
post '/webhooks/paybygroup' do
  request.body.rewind
  payload_body = request.body.read
  verify_signature(payload_body)
  puts 'Webhook is valid!'
end

def verify_signature(payload_body)
  signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), ENV['PBG_SECRET_TOKEN'], payload_body)
  return halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, request.env['HTTP_X_PBG_SIGNATURE'])
end

Warning

Never hardcode the secret token into your app! As you can see in the example, we’re using an environment variable to hold that value.

Suggest Edits

Purchase claimed

 

When an organizer provides the necessary details to claim a purchase and either already has or creates an account to manage the purchase going forward.

POST https://yoursite.com/webhooks/paybygroup
X-Event-ID: 9hdfa-49fa-isdj3-askn3
X-PBG-Signature: i3j4fniosdfoajs934ncaksc8h4fias

{
  "type": "purchase_claimed",
  "api_version": "1",
  "published_at": "2018-10-22T12:34:56Z",
  "error": null,
  "data": {
    "purchase": {
      "id": "7d0aa011-c224-4c77-91ce-8ad28fec33fa",
      "slug": "3FlBwR",
      "status": "active",
      "currency_code": "USD",
      "next_payment_due_deadline": "2018-07-14T11:02:49-04:00",
      "next_payment_due_deadline_timezone": "America/New_York",      
      "product": {
        "cost_type": "total",
        "costs": [
          {
            "amount": {
              "amount_cents": 100000,
              "currency_code": "USD"
            },
            "min_slots": 1,
            "max_slots": null
          }
        ],
        "description": "Weekend package for Las Vegas.",
        "name": "Trip to Las Vegas!",
        "start_datetime": "2018-08-25T11:02:49-07:00",
        "start_datetime_timezone": "America/Los_Angeles",        
        "end_datetime": "2018-09-06T11:02:49-07:00",
        "end_datetime_timezone": "America/Los_Angeles",               
        "external_purchase_id": null,
        "inventory_id": null,
        "link": null
      },
      "group": {
        "commit_deadline": "2018-06-13T11:02:49-04:00",
        "commit_deadline_timezone": "America/New_York",
        "max_slots": null,
        "min_slots": 2,
        "min_contribution": null,
        "organizer_email": "john@example.com",
        "organizer_full_name": "John Doe",
        "split_type": "even_split"
      },
      "tipped": false,
      "auto_pilot_enabled": false,
      "auto_pilot_trigger_slots": null,
      "current_product_cost_amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "current_total_cost_amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "has_consumer_field_schemas": false,
      "consumer_field_values": [],
      "refund_status": "none",
      "processing_refund": false,
      "language_code": "en",
      "confirmation_url": null,
      "metadata": {},
      "created_at": "2018-05-11T11:02:49Z"
      "payments": [
        {
          "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
          "status": "active",
          "number": 0,
          "percentage": 100,
          "due_deadline": "2018-10-29T21:19:49-04:00",
          "due_deadline_timezone": "America/New_York",
          "amount": null,
          "submitted_at": null,
          "accepted_at": null,
          "paid_at": null,
          "processing_currency": "USD",
          "conversion_rate": null,
          "failed": false,
          "payout_failed": false
        }
      ]
    }
  }
}
Suggest Edits

Purchase updated

 

When changes are made to the purchase, either by the merchant or by the organizer, this event occurs.

POST https://yoursite.com/webhooks/paybygroup
X-Event-ID: 9hdfa-49fa-isdj3-askn3
X-PBG-Signature: i3j4fniosdfoajs934ncaksc8h4fias

{
  "type": "purchase_updated",
  "api_version": "1",
  "published_at": "2018-10-22T12:34:56Z",
  "error": null,
  "data": {
    "purchase": {
      "id": "7d0aa011-c224-4c77-91ce-8ad28fec33fa",
      "slug": "3FlBwR",
      "status": "active",
      "currency_code": "USD",
      "next_payment_due_deadline": "2018-07-14T11:02:49-04:00",
      "next_payment_due_deadline_timezone": "America/New_York",      
      "product": {
        "cost_type": "total",
        "costs": [
          {
            "amount": {
              "amount_cents": 100000,
              "currency_code": "USD"
            },
            "min_slots": 1,
            "max_slots": null
          }
        ],
        "description": "Weekend package for Las Vegas.",
        "name": "Trip to Las Vegas!",
        "start_datetime": "2018-08-25T11:02:49-07:00",
        "start_datetime_timezone": "America/Los_Angeles",        
        "end_datetime": "2018-09-06T11:02:49-07:00",
        "end_datetime_timezone": "America/Los_Angeles",               
        "external_purchase_id": null,
        "inventory_id": null,
        "link": null
      },
      "group": {
        "commit_deadline": "2018-06-13T11:02:49-04:00",
        "commit_deadline_timezone": "America/New_York",        
        "max_slots": null,
        "min_slots": 2,
        "min_contribution": null,
        "organizer_email": "john@example.com",
        "organizer_full_name": "John Doe",
        "split_type": "even_split"
      },
      "tipped": false,
      "auto_pilot_enabled": false,
      "auto_pilot_trigger_slots": null,
      "current_product_cost_amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "current_total_cost_amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "has_consumer_field_schemas": false,
      "consumer_field_values": [],
      "refund_status": "none",
      "processing_refund": false,
      "language_code": "en",
      "confirmation_url": null,
      "metadata": {},
      "created_at": "2018-05-11T11:02:49Z"
      "payments": [
        {
          "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
          "status": "active",
          "number": 0,
          "percentage": 100,
          "due_deadline": "2018-10-29T21:19:49-04:00",
          "due_deadline_timezone": "America/New_York",
          "amount": null,
          "submitted_at": null,
          "accepted_at": null,
          "paid_at": null,
          "processing_currency": "USD",
          "conversion_rate": null,
          "failed": false,
          "payout_failed": false
        }
      ]
    }
  }
}
Suggest Edits

Purchase canceled

 

This event occurs when either the merchant or the organizer cancels a purchase.

POST https://yoursite.com/webhooks/paybygroup
X-Event-ID: 9hdfa-49fa-isdj3-askn3
X-PBG-Signature: i3j4fniosdfoajs934ncaksc8h4fias

{
  "type": "purchase_canceled",
  "api_version": "1",
  "published_at": "2018-10-22T12:34:56Z",
  "error": null,
  "data": {
    "purchase": {
      "id": "7d0aa011-c224-4c77-91ce-8ad28fec33fa",
      "slug": "3FlBwR",
      "status": "canceled",
      "currency_code": "USD",
      "next_payment_due_deadline": null,
      "next_payment_due_deadline_timezone": null,      
      "product": {
        "cost_type": "total",
        "costs": [
          {
            "amount": {
              "amount_cents": 100000,
              "currency_code": "USD"
            },
            "min_slots": 1,
            "max_slots": null
          }
        ],
        "description": "Weekend package for Las Vegas.",
        "name": "Trip to Las Vegas!",
        "start_datetime": "2018-08-25T11:02:49-07:00",
        "start_datetime_timezone": "America/Los_Angeles",        
        "end_datetime": "2018-09-06T11:02:49-07:00",
        "end_datetime_timezone": "America/Los_Angeles",               
        "external_purchase_id": null,
        "inventory_id": null,
        "link": null
      },
      "group": {
        "commit_deadline": "2018-06-13T11:02:49Z",
        "commit_deadline_timezone": null,
        "max_slots": null,
        "min_slots": 2,
        "min_contribution": null,
        "organizer_email": "john@example.com",
        "organizer_full_name": "John Doe",
        "split_type": "even_split"
      },
      "tipped": false,
      "auto_pilot_enabled": false,
      "auto_pilot_trigger_slots": null,
      "current_product_cost_amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "current_total_cost_amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "has_consumer_field_schemas": false,
      "consumer_field_values": [],
      "refund_status": "none",
      "processing_refund": false,
      "language_code": "en",
      "confirmation_url": null,
      "metadata": {},
      "created_at": "2018-05-11T11:02:49Z"
      "payments": [
        {
          "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
          "status": "active",
          "number": 0,
          "percentage": 100,
          "due_deadline": "2018-10-29T21:19:49-04:00",
          "due_deadline_timezone": "America/New_York",
          "amount": null,
          "submitted_at": null,
          "accepted_at": null,
          "paid_at": null,
          "processing_currency": "USD",
          "conversion_rate": null,
          "failed": false,
          "payout_failed": false
        }
      ]
    }
  }
}
Suggest Edits

Payment authorized

 

When a purchase's payment is submitted (all members have committed and the total funds required have been authorized across the group members' cards), we will notify you so you can accept, mark unavailable, or reject the Payment (see Completing a Purchase).

POST https://yoursite.com/webhooks/paybygroup
X-Event-ID: 9hdfa-49fa-isdj3-askn3
X-PBG-Signature: i3j4fniosdfoajs934ncaksc8h4fias

{
  "type": "payment_authorized",
  "api_version": 1,
  "published_at": "2018-10-12T00:32:59Z",  
  "error": null,
  "data": {
    "payment": {
      "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
      "purchase": {
        "id": "7d0aa011-c224-4c77-91ce-8ad28fec33fa",
        "slug": "3FlBwR",
        "status": "active",
        "currency_code": "USD",
        "next_payment_due_deadline": null,
        "next_payment_due_deadline_timezone": null,        
        "product": {
          "cost_type": "total",
          "costs": [
            {
              "amount": {
                "amount_cents": 100000,
                "currency_code": "USD"
              },
              "min_slots": 1,
              "max_slots": null
            }
          ],
          "description": "Weekend package for Las Vegas.",
          "name": "Trip to Las Vegas!",
          "start_datetime": "2018-08-25T11:02:49-07:00",
          "start_datetime_timezone": "America/Los_Angeles",         
          "end_datetime": "2018-09-06T11:02:49-07:00",
          "end_datetime_timezone": "America/Los_Angeles",               
          "external_purchase_id": null,
          "inventory_id": null,
          "link": null
        },
        "group": {
          "commit_deadline": "2018-10-13T11:02:49Z",
          "commit_deadline_timezone": nuill,          
          "max_slots": null,
          "min_slots": 2,
          "min_contribution": null,
          "organizer_email": "john@example.com",
          "organizer_full_name": "John Doe",
          "split_type": "even_split"
        },
        "tipped": true,
        "auto_pilot_enabled": false,
        "auto_pilot_trigger_slots": null,
        "current_product_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "current_total_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "has_consumer_field_schemas": false,
        "consumer_field_values": [],
        "refund_status": "none",
        "processing_refund": false,
        "language_code": "en",
        "confirmation_url": null,
        "metadata": {},
        "created_at": "2018-05-11T11:02:49Z"
        "payments": [
          {
            "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
            "status": "authorized",
            "number": 0,
            "percentage": 100,
            "due_deadline": "2018-10-29T21:19:49-04:00",
            "due_deadline_timezone": "America/New_York",
            "amount": {
              "amount_cents": 100000,
              "currency_code": "USD"
            },
            "submitted_at": "2018-10-12T00:32:50Z",
            "accepted_at": null,
            "paid_at": null,
            "processing_currency": "USD",
            "conversion_rate": 1,
            "failed": false,
            "payout_failed": false
          }
        ]        
      },
      "status": "authorized",
      "number": 0,
      "percentage": 100,
      "due_deadline": "2018-10-29T21:19:49-04:00",
      "due_deadline_timezone": "America/New_York",
      "amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "submitted_at": "2018-10-12T00:32:50Z",
      "accepted_at": null,
      "paid_at": null,
      "processing_currency": "USD",
      "conversion_rate": 1,
      "failed": false,
      "payout_failed": false
    }
  }
}
Suggest Edits

Payment captured

 

After you accept a purchase, Pay By Group captures contributions comprising that payment from all group members. Once the full payment has been captured, this webhook is sent.

POST https://yoursite.com/webhooks/paybygroup
X-Event-ID: 9hdfa-49fa-isdj3-askn3
X-PBG-Signature: i3j4fniosdfoajs934ncaksc8h4fias

{
  "type": "payment_captured",
  "api_version": "1",
  "published_at": "2018-10-12T12:34:56Z",
  "error": null,
  "data": {
    "payment": {
      "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
      "purchase": {
        "id": "7d0aa011-c224-4c77-91ce-8ad28fec33fa",
        "slug": "3FlBwR",
        "status": "active",
        "currency_code": "USD",
        "next_payment_due_deadline": null,
        "next_payment_due_deadline_timezone": null,      
        "product": {
          "cost_type": "total",
          "costs": [
            {
              "amount": {
                "amount_cents": 100000,
                "currency_code": "USD"
              },
              "min_slots": 1,
              "max_slots": null
            }
          ],
          "description": "Weekend package for Las Vegas.",
          "name": "Trip to Las Vegas!",
          "start_datetime": "2018-08-25T11:02:49-0700:00",
          "start_datetime_timezone": "America/Los_Angeles",               
          "end_datetime": "2018-09-06T11:02:49-07:00",
          "end_datetime_timezone": "America/Los_Angeles",
          "external_purchase_id": null,
          "inventory_id": null,
          "link": null
        },
        "group": {
          "commit_deadline": "2018-10-13T11:02:49Z",
          "commit_deadline_timezone": null,
          "max_slots": null,
          "min_slots": 2,
          "min_contribution": null,
          "organizer_email": "john@example.com",
          "organizer_full_name": "John Doe",
          "split_type": "even_split"
        },
        "tipped": true,
        "auto_pilot_enabled": false,
        "auto_pilot_trigger_slots": null,
        "current_product_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "current_total_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "has_consumer_field_schemas": false,
        "consumer_field_values": [],
        "refund_status": "none",
        "processing_refund": false,
        "language_code": "en",
        "confirmation_url": null,
        "metadata": {},
        "created_at": "2018-05-11T11:02:49Z"
        "payments": [
          {
            "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
            "status": "processing_payout",
            "number": 0,
            "percentage": 100,
            "due_deadline": "2018-10-29T21:19:49-04:00",
            "due_deadline_timezone": "America/New_York",
            "amount": {
              "amount_cents": 100000,
              "currency_code": "USD"
            },
            "submitted_at": "2018-10-12T00:32:50Z",
            "accepted_at": null,
            "paid_at": null,
            "processing_currency": "USD",
            "conversion_rate": 1,
            "failed": false,
            "payout_failed": false
          }
        ]
      },
      "status": "processing_payout",
      "number": 0,
      "percentage": 100,
      "due_deadline": "2018-10-29T21:19:49-04:00",
      "due_deadline_timezone": "America/New_York",
      "amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "submitted_at": "2018-10-12T00:32:50Z",
      "accepted_at": "2018-05-12T00:40:54Z",
      "paid_at": null,
      "processing_currency": "USD",
      "conversion_rate": 1,
      "failed": false,
      "payout_failed": false
    }
  }
}
Suggest Edits

Payment paid out

 

If your payment destination is a bank account, then after a payment is captured, Pay By Group settles payment for the full amount to your bank account. This webhook confirms those funds have been settled to you.

If your payment destination is a gateway, then you will receive this webhook immediately following the Payment Captured webhook.

See Setup for determining which payment destination type you should use.

POST https://yoursite.com/webhooks/paybygroup
X-Event-ID: 9hdfa-49fa-isdj3-askn3
X-PBG-Signature: i3j4fniosdfoajs934ncaksc8h4fias

{
  "type": "payment_paid",
  "api_version": "1",
  "published_at": "2018-10-22T12:34:56Z",
  "error": null,
  "data": {
    "payment": {
      "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
      "purchase": {
        "id": "7d0aa011-c224-4c77-91ce-8ad28fec33fa",
        "slug": "3FlBwR",
        "status": "active",
        "currency_code": "USD",
        "next_payment_due_deadline": null,
        "next_payment_due_deadline_timezone": null,        
        "product": {
          "cost_type": "total",
          "costs": [
            {
              "amount": {
                "amount_cents": 100000,
                "currency_code": "USD"
              },
              "min_slots": 1,
              "max_slots": null
            }
          ],
          "description": "Weekend package for Las Vegas.",
          "name": "Trip to Las Vegas!",
          "start_datetime": "2018-08-25T11:02:49-07:00",
          "start_datetime_timezone": "America/Los_Angeles",          
          "end_datetime": "2018-09-06T11:02:49-07:00",
          "end_datetime_timezone": "America/Los_Angeles",          
          "external_purchase_id": null,
          "inventory_id": null,
          "link": null
        },
        "group": {
          "commit_deadline": "2018-06-13T11:02:49Z",
          "commit_deadline_timezone": null,
          "max_slots": null,
          "min_slots": 2,
          "min_contribution": null,
          "organizer_email": "john@example.com",
          "organizer_full_name": "John Doe",
          "split_type": "even_split"
        },
        "tipped": true,
        "auto_pilot_enabled": false,
        "auto_pilot_trigger_slots": null,
        "current_product_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "current_total_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "has_consumer_field_schemas": false,
        "consumer_field_values": [],
        "refund_status": "none",
        "processing_refund": false,
        "language_code": "en",
        "confirmation_url": null,
        "metadata": {},
        "created_at": "2018-05-11T11:02:49Z"
        "payments": [
          {
            "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
            "status": "paid",
            "number": 0,
            "percentage": 100,
            "due_deadline": "2018-10-29T21:19:49-04:00",
            "due_deadline_timezone": "America/New_York",
            "amount": {
              "amount_cents": 100000,
              "currency_code": "USD"
            },
            "submitted_at": "2018-10-12T00:32:50Z",
            "accepted_at": "2018-10-12T00:40:54Z",
            "paid_at": "2018-10-12T00:47:17Z",
            "processing_currency": "USD",
            "conversion_rate": 1,
            "failed": false,
            "payout_failed": false
          }
        ]        
      },
      "status": "paid",
      "number": 0,
      "percentage": 100,
      "due_deadline": "2018-10-29T21:19:49-04:00",
      "due_deadline_timezone": "America/New_York",
      "amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "submitted_at": "2018-10-12T00:33:02Z",
      "accepted_at": "2018-10-12T00:40:54Z",
      "paid_at": "2018-10-12T00:47:17Z",
      "processing_currency": "USD",
      "conversion_rate": 1,
      "failed": false,
      "payout_failed": false
    }
  }
}
Suggest Edits

Payment expired

 

When the due_deadline of the current payment expires before the group successfully makes the payment towards the purchase, we notify you so you can cancel the purchase or extend the deadline (see Modifying a Purchase).

POST https://yoursite.com/webhooks/paybygroup
X-Event-ID: 9hdfa-49fa-isdj3-askn3
X-PBG-Signature: i3j4fniosdfoajs934ncaksc8h4fias

{
  "type": "payment_expired",
  "api_version": "1",
  "published_at": "2018-10-22T12:34:56Z",
  "error": null,
  "data": {
    "payment": {
      "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
      "purchase": {
        "id": "7d0aa011-c224-4c77-91ce-8ad28fec33fa",
        "slug": "3FlBwR",
        "status": "active",
        "currency_code": "USD",
        "next_payment_due_deadline": null,
        "next_payment_due_deadline_timezone": null,        
        "product": {
          "cost_type": "total",
          "costs": [
            {
              "amount": {
                "amount_cents": 100000,
                "currency_code": "USD"
              },
              "min_slots": 1,
              "max_slots": null
            }
          ],
          "description": "Weekend package for Las Vegas.",
          "name": "Trip to Las Vegas!",
          "start_datetime": "2018-08-25T11:02:49-07:00",
          "start_datetime_timezone": "America/Los_Angeles",          
          "end_datetime": "2018-09-06T11:02:49-07:00",
          "end_datetime_timezone": "America/Los_Angeles",          
          "external_purchase_id": null,
          "inventory_id": null,
          "link": null
        },
        "group": {
          "commit_deadline": "2018-06-13T11:02:49Z",
          "commit_deadline_timezone": null,          
          "max_slots": null,
          "min_slots": 2,
          "min_contribution": null,
          "organizer_email": "john@example.com",
          "organizer_full_name": "John Doe",
          "split_type": "even_split"
        },
        "tipped": true,
        "auto_pilot_enabled": false,
        "auto_pilot_trigger_slots": null,
        "current_product_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "current_total_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "has_consumer_field_schemas": false,
        "consumer_field_values": [],
        "refund_status": "none",
        "processing_refund": false,
        "language_code": "en",
        "confirmation_url": null,
        "metadata": {},
        "created_at": "2018-05-11T11:02:49Z"
        "payments": [
          {
            "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
            "status": "active",
            "number": 0,
            "percentage": 100,
            "due_deadline": "2018-10-29T21:19:49-04:00",
            "due_deadline_timezone": "America/New_York",
            "amount": {
              "amount_cents": 100000,
              "currency_code": "USD"
            },
            "submitted_at": null,
            "accepted_at": null,
            "paid_at": null,
            "processing_currency": "USD",
            "conversion_rate": 1,
            "failed": false,
            "payout_failed": false
          }
        ]                
      },
      "status": "active",
      "number": 0,
      "percentage": 100,
      "due_deadline": "2018-10-29T21:19:49-04:00",
      "due_deadline_timezone": "America/New_York",
      "amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "submitted_at": null,
      "accepted_at": null,
      "paid_at": null,
      "processing_currency": "USD",
      "conversion_rate": 1,
      "failed": false,
      "payout_failed": false
    }
  }
}
Suggest Edits

Member refunded

 

Because some refunds may not be confirmed instantly due to our having to pull funds from your bank account to fund the refund or other similar reasons, for each refund you trigger to a member we will send this webhook once it has fully succeeded and the customer has been sent the refund via their original payment method.

POST https://yoursite.com/webhooks/paybygroup
X-Event-ID: 9hdfa-49fa-isdj3-askn3
X-PBG-Signature: i3j4fniosdfoajs934ncaksc8h4fias

{
  "type": "membership_refunded",
  "api_version": "1",
  "published_at": "2018-10-31T12:34:56Z",
  "error": null,
  "data": {
    "membership": {
      "id": "aa25b331-6c38-246d-3edc-bfaa6483385a",
      "purchase": {
        "id": "7d0aa011-c224-4c77-91ce-8ad28fec33fa",
        "slug": "3FlBwR",
        "status": "active",
        "currency_code": "USD",
        "next_payment_due_deadline": null,
        "next_payment_due_deadline_timezone": null,        
        "product": {
          "cost_type": "total",
          "costs": [
            {
              "amount": {
                "amount_cents": 100000,
                "currency_code": "USD"
              },
              "min_slots": 1,
              "max_slots": null
            }
          ],
          "description": "Weekend package for Las Vegas.",
          "name": "Trip to Las Vegas!",
          "start_datetime": "2018-08-25T11:02:49-07:00",
          "start_datetime_timezone": "America/Los_Angeles",          
          "end_datetime": "2018-09-06T11:02:49-07:00",
          "end_datetime_timezone": "America/Los_Angeles",          
          "external_purchase_id": null,
          "inventory_id": null,
          "link": null
        },
        "group": {
          "commit_deadline": "2018-06-13T11:02:49Z",
          "commit_deadline_timezone": null,          
          "max_slots": null,
          "min_slots": 2,
          "min_contribution": null,
          "organizer_email": "john@example.com",
          "organizer_full_name": "John Doe",
          "split_type": "even_split"
        },
        "tipped": true,
        "auto_pilot_enabled": false,
        "auto_pilot_trigger_slots": null,
        "current_product_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "current_total_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "has_consumer_field_schemas": false,
        "consumer_field_values": [],
        "refund_status": "none",
        "processing_refund": false,
        "language_code": "en",
        "confirmation_url": null,
        "metadata": {},
        "created_at": "2018-05-11T11:02:49Z"
        "payments": [
          {
            "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
            "status": "paid",
            "number": 0,
            "percentage": 100,
            "due_deadline": "2018-10-29T21:19:49-04:00",
            "due_deadline_timezone": "America/New_York",
            "amount": {
              "amount_cents": 100000,
              "currency_code": "USD"
            },
            "submitted_at": "2018-10-12T00:32:50Z",
            "accepted_at": "2018-10-12T00:40:54Z",
            "paid_at": "2018-10-12T00:47:17Z",
            "processing_currency": "USD",
            "conversion_rate": 1,
            "failed": false,
            "payout_failed": false
          }
        ]        
      },
      "status": "committed",
      "refund_status": "full",
      "failed": false,
      "short": false,
      "role": "invitee",
      "claimed_slots": 1,
      "opt_in_marketing": true,
      "share_amount": {
        "amount_cents": 50000,
        "currency_code": "USD"      
      },
      "fees": {
        "consumer_fee": {
          "amount_cents": 250,
          "currency_code": "USD"
        },
        "merchant_service_fee": {
          "amount_cents": 0,
          "currency_code": "USD"
        }
      },
      "consumer_field_values": [],
      "collected_share_amount": {
        "amount_cents": 0,
        "currency_code": "USD"
      },
      "user": {
        "id": "b2977f06-8145-141f-943b-b336190be3a8",
        "email": "john@example.com",
        "full_name": "John Doe"
      },
      "committed_at": "2018-05-12T00:32:50Z"
    }
  }
}
Suggest Edits

Payment authorize failed

 

You will receive this webhook if an authorization fails when a group leader submits the group's payment or it is triggered by auto-pilot. However, this is purely for notice purposes. You don't need to take any action because our system will automatically resolve the issue with the group members and trigger another Payment authorized webhook to you.

POST https://yoursite.com/webhooks/paybygroup
X-Event-ID: 9hdfa-49fa-isdj3-askn3
X-PBG-Signature: i3j4fniosdfoajs934ncaksc8h4fias

{
  "type": "payment_authorize_failed",
  "api_version": "1",
  "published_at": "2018-10-22T12:34:56Z",
  "error": "Authorization failed - check your card info, contact your bank to approve the charge, or use a new card.",
  "data": {
    "payment": {
      "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
      "purchase": {
        "id": "7d0aa011-c224-4c77-91ce-8ad28fec33fa",
        "slug": "3FlBwR",
        "status": "active",
        "currency_code": "USD",
        "next_payment_due_deadline": "2018-10-29T21:19:49-04:00",
        "next_payment_due_deadline_timezone": "America/New_York",        
        "product": {
          "cost_type": "total",
          "costs": [
            {
              "amount": {
                "amount_cents": 100000,
                "currency_code": "USD"
              },
              "min_slots": 1,
              "max_slots": null
            }
          ],
          "description": "Weekend package for Las Vegas.",
          "name": "Trip to Las Vegas!",
          "start_datetime": "2018-08-25T11:02:49-07:00",
          "start_datetime_timezone": "America/Los_Angeles",          
          "end_datetime": "2018-09-06T11:02:49-07:00",
          "end_datetime_timezone": "America/Los_Angeles",          
          "external_purchase_id": null,
          "inventory_id": null,
          "link": null
        },
        "group": {
          "commit_deadline": "2018-06-13T11:02:49Z",
          "commit_deadline_timezone": null,
          "max_slots": null,
          "min_slots": 2,
          "min_contribution": null,
          "organizer_email": "john@example.com",
          "organizer_full_name": "John Doe",
          "split_type": "even_split"
        },
        "tipped": true,
        "auto_pilot_enabled": false,
        "auto_pilot_trigger_slots": null,
        "current_product_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "current_total_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "has_consumer_field_schemas": false,
        "consumer_field_values": [],
        "refund_status": "none",
        "processing_refund": false,
        "language_code": "en",
        "confirmation_url": null,
        "metadata": {},
        "created_at": "2018-05-11T11:02:49.200493000+00:00"
        "payments": [
          {
            "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
            "status": "active",
            "number": 0,
            "percentage": 100,
            "due_deadline": "2018-10-29T21:19:49-04:00",
            "due_deadline_timezone": "America/New_York",
            "amount": {
              "amount_cents": 100000,
              "currency_code": "USD"
            },
            "submitted_at": null,
            "accepted_at": null,
            "paid_at": null,
            "processing_currency": "USD",
            "conversion_rate": 1,
            "failed": true,
            "payout_failed": false
          }
        ]  
      },
      "status": "active",
      "number": 0,
      "percentage": 100,
      "due_deadline": "2018-10-29T21:19:49-04:00",
      "due_deadline_timezone": "America/New_York",
      "amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "submitted_at": "null",
      "accepted_at": null,
      "paid_at": null,
      "processing_currency": "USD",
      "conversion_rate": 1,
      "failed": true,
      "payout_failed": false
    }
  }
}
Suggest Edits

Payment capture failed

 

This is an extremely rare case, but when there is a problem with capturing authorized contributions from group members after you accept a payment, you will receive a failure. We will also automatically notify the failed group members to get them to resolve the issue and, once they do, resubmit the payment for your acceptance.

POST https://yoursite.com/webhooks/paybygroup
X-Event-ID: 9hdfa-49fa-isdj3-askn3
X-PBG-Signature: i3j4fniosdfoajs934ncaksc8h4fias

{
  "type": "payment_capture_failed",
  "api_version": "1",
  "published_at": "2018-10-22T12:34:56Z",
  "error": "Payment contribution failed to capture.",
  "data": {
    "payment": {
      "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
      "purchase": {
        "id": "7d0aa011-c224-4c77-91ce-8ad28fec33fa",
        "slug": "3FlBwR",
        "status": "active",
        "currency_code": "USD",
        "next_payment_due_deadline": "2018-06-13T11:02:49-04:00",
        "next_payment_due_deadline_timezone": "America/New_York",        
        "product": {
          "cost_type": "total",
          "costs": [
            {
              "amount": {
                "amount_cents": 100000,
                "currency_code": "USD"
              },
              "min_slots": 1,
              "max_slots": null
            }
          ],
          "description": "Weekend package for Las Vegas.",
          "name": "Trip to Las Vegas!",
          "start_datetime": "2018-08-25T11:02:49-07:00",
          "start_datetime_timezone": "America/Los_Angeles",          
          "end_datetime": "2018-09-06T11:02:49-07:00",
          "end_datetime_timezone": "America/Los_Angeles",          
          "external_purchase_id": null,
          "inventory_id": null,
          "link": null
        },
        "group": {
          "commit_deadline": "2018-06-13T11:02:49-04:00",
          "commit_deadline_timezone: "America/New_York",
          "max_slots": null,
          "min_slots": 2,
          "min_contribution": null,
          "organizer_email": "john@example.com",
          "organizer_full_name": "John Doe",
          "split_type": "even_split"
        },
        "tipped": true,
        "auto_pilot_enabled": false,
        "auto_pilot_trigger_slots": null,
        "current_product_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "current_total_cost_amount": {
          "amount_cents": 100000,
          "currency_code": "USD"
        },
        "has_consumer_field_schemas": false,
        "consumer_field_values": [],
        "refund_status": "none",
        "processing_refund": false,
        "language_code": "en",
        "confirmation_url": null,
        "metadata": {},
        "created_at": "2018-05-11T11:02:49Z"
        "payments": [
          {
            "id": "3f11bbdc-1dbc-4713-903b-2ef3258ed2cd",
            "status": "active",
            "number": 0,
            "percentage": 100,
            "due_deadline": "2018-10-29T21:19:49-04:00",
            "due_deadline_timezone": "America/New_York",
            "amount": {
              "amount_cents": 100000,
              "currency_code": "USD"
            },
            "submitted_at": "2018-10-12T00:32:50Z",
            "accepted_at": null,
            "paid_at": null,
            "processing_currency": "USD",
            "conversion_rate": 1,
            "failed": true,
            "payout_failed": false
          }
        ]                
      },
      "status": "active",
      "number": 0,
      "percentage": 100,
      "due_deadline": "2018-10-29T21:19:49-04:00",
      "due_deadline_timezone": "America/New_York",
      "amount": {
        "amount_cents": 100000,
        "currency_code": "USD"
      },
      "submitted_at": "2018-10-12T00:32:50Z",
      "accepted_at": null,
      "paid_at": null,
      "processing_currency": "USD",
      "conversion_rate": 1,
      "failed": true,
      "payout_failed": false
    }
  }
}