Marketplaces

This guide explains how to accept payments and move funds to the bank accounts of your sellers, by enabling Swifter as a payment integration on your marketplace.

When a seller activates Swifter as a payment method by onboarding on Swifter and configuring the API keys, payments can be collected on the seller website via ACH. The funds will be automatically settled into the seller's Swifter account and the seller fee will get settled into the marketplace's Swifter account.

Prerequisites

Register your platform, as a software business.
Add business details to activate your account.

Set up the SDK

Follow the steps to collect an online payment.

Create a Session whenever the customer intends to pay online and get a sessionID.

Tag every transaction created with a marketplace_id. This will ensure that the seller fee for each transaction is accumulated in your Swifter account.

Request Parameter	Data Type	Field
amount	integer	required
type	string	required
consumer_info	{ "first_name": string, "last_name": string }	required
marketplace_id	string	required

curl --request POST \
     --url https://api.swifterhq.com/api/v2.0/sessions \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --data "{\"amount\": \"1000\",\"marketplace_id\": \"mk_org_123456789\",\"type\":\"consumer_checkout\",\"consumer_info\":{\"first_name\": \"First\",\"last_name\": \"Last\",\"email\": \"user@email.com\",\"phone\": \"+19999999999\",\"drivers_license\": \"XXXXXXXX\"}}"

const sdk = require('api')('@payswifter/v1.0#1f7erlgkue3ynzm');

const request = {
    "amount": 1000,
    "type": "consumer_checkout",
  	"marketplace_id": "mk_org_123456789",
    "consumer_info": {
        "first_name": "User",
        "last_name": "Name",
        "phone": "+19999999999",
        "email": "user@email.com",
        "drivers_license": "XXXXXXX"
    }
};

sdk['create_session_sessions_post']()
  .then(res => console.log(res))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.swifterhq.com/api/v2.0/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'

response = http.request(request)
puts response.read_body

import requests

url = "https://api.swifterhq.com/api/v2.0/sessions"

headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, headers=headers)

print(response.text)

{
    "id": "sess_7zujHTary67CkKEPJnZ7ht",
    "create_date": "2023-02-28T06:09:37.694962+00:00",
    "status": "started",
    "organization_id": "org_3bysdyt7dvBrZK7kRGQBRg",
    "type": "consumer_checkout",
    "total_amount": 1000,
    "is_valid_consumer": false,
    "is_valid_bank_account_selected": false,
    "is_sufficient_funds": false,
    "consent_text": "I authorize Swifter to debit my bank account and save my authorization for future use with Swifter.",
    "fees": 150,
    "track_number": "hfyx47",
    "marketplace_id": "mk_org_123456789"
}

To use Swifter JS, include the following script inside the head tag on the checkout page wherever the customer intends to pay with ACH.

<script src="https://js.payswifter.com/v1.js"></script>
<script type="text/javascript"></script>

SwifterPay is now available for use in your Javascript code. Create a new instance and configure the generated session ID. The payment modal will be overlayed on top of the page, until the consumer exits the authorization flow. Use onComplete and onExit functions to trigger the next set of actions, upon completion of authorization by the consumer. The below snippet will open the modal.

const sp = new SwifterPay();
    sp.startSession({
      sessionID: '{SESSION_ID}',
      selector: 'body',
      renderInModal: true,
      onComplete: (response) => {
        // Called on successful session completion
      },
      onExit: (response) => {
      // Called on a failed session
      }
});

Sample Success Response

{
  createdDate: '2021-12-19T03:33:28.574215+00:00', 
  fees: 150, 
  referenceId: 'hfyx47', 
  tip: null, 
  orderAmount: 100, 
  totalAmount: 250
}

Sample error response

List of all the error codes can be found here.

{
  type: 'session_insufficient_balance',
  code: null
}

On successful session completion, create an order to acknowledge the payment authorization and to associate it with an order on your system.

curl --request POST \
     --url https://api.swifterhq.com/api/v2.0/orders \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --data "{\"session_id\":\"{sessionId}\"}}"

const sdk = require('api')('@payswifter/v1.0#1f7erlgkue3ynzm');

const request = {
	"sessionID":"SESSION_ID_FROM_SPARCPAYAPI",
  "storeIdentifier":"STORE_ID"
};

sdk['create_order_orders_post']()
  .then(res => console.log(res))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.swifterhq.com/api/v2.0/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'

response = http.request(request)
puts response.read_body

import requests

url = "https://api.swifterhq.com/api/v2.0/orders"

headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, headers=headers)

print(response.text)

{
    "order": {
        "id": "order_QtkysnatwsYPqPJKpZmDwS",
        "create_date": "2023-02-28T08:53:46.372766+00:00",
        "store_id": "store_GbLiv48kSEHTaBVS6SUPCc",
        "charge_id": null,
        "organization_id": "org_3bysdyt7dvBrZK7kRGQBRg",
        "marketplace_id": "mk_org_123456789",
        "delivered_date": null,
        "total_amount": 1000,
        "status": "submitted",
        "track_number": "hfyx47",
        "updated_at": "2023-02-28T08:53:46.372766+00:00"
    },
    "session": {
        "id": "sess_7zujHTary67CkKEPJnZ7ht",
        "create_date": "2023-02-28T06:09:37.694962+00:00",
        "status": "finalized ",
        "organization_id": "org_3bysdyt7dvBrZK7kRGQBRg",
        "type": "consumer_checkout",
        "total_amount": 1000,
        "is_valid_consumer": true,
        "is_valid_bank_account_selected": true,
        "is_sufficient_funds": true,
        "consent_text": "I authorize Swifter to debit my bank account and save my authorization for future use with Swifter.",
        "fees": 150,
        "track_number": "hfyx47",
        "marketplace_id": null
    }
}

Based on your fulfilment flow, charge the order whenever you want to capture the payment. This will submit the payment for ACH processing, which will be fully managed by Swifter.

curl --request POST \
     --url https://api.swifterhq.com/api/v2.0/orders/order_id/charge \
     --header 'Accept: application/json'

const sdk = require('api')('@payswifter/v1.0#1f7erlgkue3ynzm');

const request = {order_id: 'ORDER_ID'};

sdk['charge_order_by_id_orders__order_id__charge_post'](request)
  .then(res => console.log(res))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.swifterhq.com/api/v2.0/orders/order_id/charge")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'

response = http.request(request)
puts response.read_body

import requests

url = "https://api.swifterhq.com/api/v2.0/orders/order_id/charge"

headers = {"Accept": "application/json"}

response = requests.request("POST", url, headers=headers)

print(response.text)

{
    "order": {
        "id": "order_QtkysnatwsYPqPJKpZmDwS",
        "create_date": "2023-02-28T08:53:46.372766+00:00",
        "store_id": "store_GbLiv48kSEHTaBVS6SUPCc",
        "charge_id": "charge_WZJC5xQ8uxJWZZX3tBHN6n",
        "organization_id": "org_3bysdyt7dvBrZK7kRGQBRg",
        "marketplace_id": "mk_org_123456789",
        "delivered_date": "2023-02-28T09:01:11.301246+00:00",
        "total_amount": 1000,
        "status": "charged",
        "track_number": "hfyx47",
        "updated_at": "2023-02-28T09:01:11.300261+00:00"
    },
    "charge": {
        "id": "charge_WZJC5xQ8uxJWZZX3tBHN6n",
        "create_date": "2023-02-28T09:01:07.736316+00:00",
        "type": "ACH_DEBIT",
        "status": "pending",
        "amount": 1240,
        "balance_transaction_id": "bal_tran_W96vgCA9jrbHZktHVn4Mp6",
        "consumer_fi_account_id": "c_account_ga5ExB9vJKMLVEtev7dHcx",
        "business_fi_account_id": "b_account_DSBcXwMYMsfU2QUX4i8Yzu",
        "organization_id": "org_3bysdyt7dvBrZK7kRGQBRg",
        "marketplace_id": "mk_org_123456789",
        "track_number": "hfyx47"
    }
}

Onboarding a seller

Below are the steps to onboard a new seller.

Share your unique marketplace onboarding URL with your sellers.
The seller should register on Swifter and activate the store, by filling the business details.
The seller can generate the API keys from the Swifter dashboard, after activation.
The API keys can be entered on the integrations page in the marketplace, when activating Swifter as a payment provider.

Payouts

By default, any funds that are collected get settled automatically to the seller's Swifter account. The seller fess for each transaction get accumulated in your Swifter balance and are eligible for payouts on a monthly basis. You can initiate a payout on the Banking Statements page, when the account balance is greater than the holding balance.