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    

2 - Use Pay By Group's APIs

Travel website uses Pay By Group’s API for end-to-end automation

ACME is a vacation rental listing site. Instead of using Pay By Group’s JavaScript-powered checkout integration, ACME embeds the Pay By Group creation process within its checkout experience using Pay By Group’s API. Authentication is required to perform API calls.

  1. Customer picks a vacation rental property on ACME’s site and clicks the "Split the Cost" button ACME has placed on its booking page that routes to an adapted version of its checkout page.
  2. On ACME’s checkout page, the customer chooses any options ACME offers, such as travel insurance. ACME includes needed fields for creating a purchase, such as customer contact info and how they want to split the cost, because the customer chose the "Split the Cost" option on the previous booking page. When the user clicks the "Split and Book" button, ACME calls Pay By Group's Create Purchase endpoint to create the purchase:
POST /merchants/{id}/purchases
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

{
  "product": {
    "cost_type": "total",
    "costs": {
      "amount": {
        "amount_cents": "25000",
        "currency_code": "USD"
      }
    },
    "name": "Property #1",
    "description": "Beautiful beachfront house",
  },
  "currency_code": "USD",
  "payments": [
    {
      "percentage": "100",
    }
  ]
}
  1. The response includes a unique slug for ACME to interact with this purchase going forward and construct a URL as go.paybygroup.com/purchases/[SLUG] where you can redirect the customer to the ACME-branded, Pay By Group-hosted group page. It also includes all other attributes of the purchase object.

  2. The customer is then taken to a page where they can choose how to split the cost and invite friends on ACME's site. There, she can enter the emails of those with whom she wants to split the purchase. When the customer clicks on the "Send Invites" button at the end of that form, ACME first calls the Claim endpoint with details for how to split. If the merchant doesn't want to show options to the user, they can set defaults here. Then the merchant calls the Invite endpoint with the invitees' email addresses.

POST /purchases/{id}/invite
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

{
  invitees: [
    {
      "full_name": "Johnny Doe",
      "email": "johnny.doe@example.com"
    }
  ]
}
  1. ACME redirects the customer to the Pay By Group dashboard for this purchase. From this point on, Pay By Group does its magic of inviting/reminding customers and her invitees to pay for the purchase, always following ACME’s business rules and enabling ACME to treat this like a single-payer order.

  2. While invitees join the group - but before it is complete and ready to make the booking - ACME monitors the inventory the group has selected. If that inventory becomes unavailable, ACME marks the purchase as unavailable, which will notify the group leader. If the price or other aspects of the purchase change - or if ACME wants to update an unavailable purchase to apply to inventory that is available - ACME may use the Update Purchase endpoint. Note: an alternative to ACME’s internal monitoring of the inventory is for Pay By Group to monitor it using ACME’s API (see Monitoring).

PATCH /purchases/{id}
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

{
  "product": {
    "name": "Trip to Tahoe this weekend"
  }
}
  1. When the purchase is 100% committed, Pay By Group creates a new Payment for the purchase and authorizes all charges to ensure valid funds and triggers a Payment Authorized webhook to notify ACME the payment is ready for them to accept.

Note

An alternative to the webhook option is allowing Pay By Group to place an order directly using your API (see Scenario 1 - Step 7.

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

{
  "type": "payment_authorize",
  "data": {
    "payment": {
      id": "9nfa3-ask3f-9234c-kas31",
      "purchase_id": "rYNpwEaS"
    }
   },
  "api_version": "1"
}
  1. After ACME receives the webhook notification, ACME calls Pay By Group’s Get Purchase endpoint if needed to retrieve the check-in/check-out date and other purchase info not already tracked in ACME’s system for this purchase. Once ACME confirms the inventory is available and the purchase amount matches the payment required for the booking, ACME calls Pay By Group’s Accept payment endpoint. Pay By Group captures the payment and immediately settles the payment to ACME via its payment gateway.
POST /payments/{id}/accept
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
  1. (Optional) ACME may pull customer and group purchase data into their CRM or systems other than the primary booking system using Pay By Group’s List Members and Get Purchase endpoints - or by exporting the data from Pay By Group’s Business Portal.