Marketplace integration

This guide explains how to integrate with Swirepay as a marketplace—where your platform is the Merchant of Record (MoR) and sub-merchants (for example restaurants or vendors) are onboarded as contacts under your account.

Unlike Partner integration (Connect onboarding with x-destination-account and separate submerchant accounts), marketplace flows use contactType: MARKETPLACE, the x-contact-gid header on payment sessions, and applicationFee to split funds between the marketplace and each sub-merchant.

API reference

Field-level schemas, try-it-out, and full request/response bodies live in the API reference. Key endpoints are linked throughout this guide.

Platform roles

Role	Description
Marketplace	Your platform—the MoR that collects customer payments and defines marketplace earnings via applicationFee.
Contacts	Sub-merchants onboarded under the marketplace (vendors, sellers, etc.). Each contact receives a share of the net payout after fees.

End-to-end flow

Sub-merchant onboarding workflow

Step	Action	Actor	Channel	Outcome
1	Create contact	Marketplace	API	Contact in PENDING / verification state
2	Send funding link	Swirepay	Email/SMS	Sub-merchant receives onboarding URL
3	Add bank details	Sub-merchant	Swirepay UI	Banking info submitted
4	Verify bank	Swirepay	Internal	Contact status updated to VERIFIED
5	Webhook	Swirepay	Webhook	CONTACT_UPDATE triggered

Flow summary

1. Marketplace creates a contact via API with onboarding metadata (contactType: MARKETPLACE).
2. Swirepay sends a secure funding source link to the contact (or you add bank details manually).
3. Sub-merchant completes bank detail entry via Swirepay-hosted UI (for example Plaid).
4. Swirepay verifies the bank and updates contact status to VERIFIED.
5. The CONTACT_UPDATE webhook notifies your backend—see sample payload.
6. When a customer pays, include x-contact-gid on the payment session to identify the sub-merchant and applicationFee for your marketplace earnings.
7. Swirepay calculates split amounts:
   • merchant_share = applicationFee (to marketplace)
   • contact_share = net payout (to sub-merchant)
8. Transfers are created for both parties and logged for audit.
9. Funds settle to the contact share on your configured schedule (for example T+1).

Prerequisites

• Authentication: x-api-key with your secret key for server-side calls (Dashboard → Developer → Secret Key). Payment session create uses your public key—see Create payment session.
• Base URL: https://api.swirepay.com
• Amounts: All payment amounts are in minor units (cents for USD).
• Test data: Use sandbox keys and the values in Test your integration—do not embed live credentials in client apps.

---

1. Onboard sub-merchants (contacts)

There are two primary paths: send a funding source link so the vendor self-serves bank entry, or manually create the contact and funding source when you already have bank details.

Option A — Funding source link (recommended)

Single contact: Call Add Funding Source Link (POST /v1/funding-source-link) with a nested contact object. Set contactType to MARKETPLACE, marketplaceActive to true, and optional meta for your internal references.

Example request shape (trimmed):

{
  "contact": {
    "name": "Jane Doe",
    "contactType": "MARKETPLACE",
    "email": "jane@demo.com",
    "phoneNumber": "+14081234567",
    "marketplaceActive": true,
    "address": {
      "street": "1900 Lafayette Street",
      "city": "Santa Clara",
      "state": "CA",
      "postalCode": "95050",
      "countryCode": "US"
    }
  },
  "notificationType": "ALL",
  "canUpdateContactFundingSource": true,
  "meta": {
    "internalERPReference": "ABC123"
  }
}

The vendor receives an Upload Funding Source email and adds bank details via the hosted flow. When verification completes, you receive a CONTACT_UPDATE webhook with status: VERIFIED.

Deactivate a contact: PATCH /v1/contact/{contactGid} with { "marketplaceActive": false } using the contact gid from create or webhook payloads.

Bulk (Excel): Follow Bulk Upload — Flow A and API reference Bulk Funding Source Link from File.

Option B — Manual contact and funding source

Use this when you already hold the vendor's bank details.

Step 1 — Create contact: Create Contact (POST /v1/contact) with contactType: MARKETPLACE and marketplaceActive: true.

Step 2 — Add funding source: Create Funding Source with the contact's gid as contactGid and issuerBank details (or set status: VERIFIED when appropriate for your integration).

Bulk funding sources (Excel): See Bulk Upload — Flow B and Bulk Add Funding Sources from File.

For contact CRUD, funding source links, and bulk patterns in depth, see Manage Contacts.

---

2. Add payment method

Before charging a customer, create a payment method using Create Payment Method (POST /v1/payment-method).

Supported types include card, ACH (ACH_LEGACY), and wallets (Apple Pay / Google Pay in live with domain verification). In test mode, use card and bank values from Test your integration.

Example (card):

{
  "type": "CARD",
  "card": {
    "number": "4242424242424242",
    "expiryMonth": 12,
    "expiryYear": 2030,
    "cvv": "123",
    "name": "Jane Doe"
  },
  "paymentMethodBillingAddress": {
    "street": "1600 Amphitheatre Pkwy",
    "city": "Mountain View",
    "state": "CA",
    "countryCode": "US",
    "postalCode": "94043"
  }
}

Persist the returned paymentMethodGid for the payment session.

---

3. Create payment session (marketplace charge)

Create a payment session with Create Payment Session (POST /v2/payment-session).

Headers

Header	Value
Content-Type	application/json
x-api-key	Your public key (pk_test_… / pk_live_…)
x-contact-gid	Contact gid of the sub-merchant receiving the payout share

Body highlights

Field	Purpose
amount	Total charge in cents
applicationFee	Marketplace earnings in cents (your share before contact payout)
paymentMethodGid	From Create Payment Method

Example:

{
  "receiptEmail": "jane@demo.com",
  "receiptSms": "+14081234567",
  "currencyCode": "USD",
  "description": "T-Shirt Order #123",
  "statementDescriptor": "Marketplace",
  "paymentMethodType": ["CARD", "ACH_LEGACY"],
  "confirmMethod": "AUTOMATIC",
  "captureMethod": "AUTOMATIC",
  "amount": 5000,
  "paymentMethodGid": "paymentmethod-abc123",
  "applicationFee": 800
}

On success, amountReceived reflects the portion after applicationFee; Swirepay routes applicationFee to the marketplace and the net amount to the contact.

Track outcomes with Payment Center webhooks such as PAYMENT_SUCCEEDED and PAYMENT_FAILED—see Webhook delivery & payloads.

---

4. Refund payment

To refund a marketplace charge, call PATCH /v1/payment-session/{paymentSessionGid}/refund with your secret key. Include amountRefunded, refundReason (REQUESTED_BY_CUSTOMER, DUPLICATE, FRAUDULENT, or OTHER), and optional refundNote.

---

Webhooks

Configure HTTPS endpoints in Developer → Webhooks—see Webhooks (guides) for dashboard setup, signing, and the full event catalog.

Event	When it fires	Guide
CONTACT_UPDATE	Contact funding source status changes (for example to VERIFIED)	Transfer Center events · Sample payload
PAYMENT_SUCCEEDED / PAYMENT_FAILED	Payment session completes or fails	Payment Center events · Sample payloads

Subscribe to CONTACT_UPDATE so your marketplace can enable a sub-merchant for live charges only after bank verification completes, without polling contact APIs.

---

Fee calculation example (NET model)

For 10 transactions totaling $100:

• Rate: 2.6% + $0.20 flat fee per transaction
• Fees = $100 × 0.026 + 10 × $0.20 = $4.60
• Final payout = $100 − $4.60 = $95.40

Confirm fee treatment and settlement timing with your Swirepay integration contact.

---

Supported transfer types

Marketplace disbursements to contacts may use:

• ACH_MPD — Automated disbursement
• RTP_MPD — Real-time payouts

Marketplace-initiated transfers via Transfer Center can bypass standard merchant limits; direct merchant-initiated transfers remain subject to Swirepay limits.

---

Integration tips

• Always pass paymentMethodGid from payment method creation into the payment session.
• Use x-contact-gid on every marketplace payment session so settlement attributes to the correct sub-merchant.
• Set applicationFee explicitly for each charge to define marketplace earnings.
• Prefer webhooks over polling for contact verification and payment outcomes.
• Wallets (Apple Pay, Google Pay) require domain verification in live mode.

---

See also

• Partner integration — Connect onboarding and x-destination-account for submerchant accounts
• Manage Contacts — contacts, funding sources, and bulk upload
• One-time payment — token → customer → payment method → payment session
• Webhooks (guides) · Webhook delivery & payloads
• API reference: Payment Center · Transfer Center