How do I board Stripe Connect Merchants via the API?

Your goal is to use the payworks API to create a payworks Merchant that can process payments via Stripe Connect.

You would usually use the API calls explained below after
a successful OAuth worfklow has been completed with the Stripe Standalone Account or after
you have successfully created the Stripe Managed Account.

You should also have look at the Stripe Integration Recipe to get a good understanding of how to use payworks together with Stripe.

1. Create a Merchant with STRIPE as the processing path

post

/v2/merchants/

Try it out!

Request


{  
   "processingPaths":[  
      {  
         "name":"Default",
         "schemes":[  
            "VISA",
            "MASTER",
            "VISAELECTRON",
            "MAESTRO"
         ],
         "currencies":[  
            "GBP"
         ],
         "details":{  
            "institute":"STRIPE",
            "secretKey":"sk_test_sECkACoegue5vuhwXva3eN6k",
            "accountId":"acct_123AbcAa7aiN7PTk",
            "chargeMethod":"DIRECT"
         }
      }
   ],
   "name":"Stripe Merchant #42",
   "details":{  
      "publicName":"Public Merchant Name",
      "address":"42 Merchant Street",
      "zip":"SW1P 2AW",
      "city":"London",
      "country":"GB",
      "contact":"+44 (170) 1234567"
   },
   "readers":[  
   ]
}

Please pay special attention to those parameters:

$.processingPaths.currencies: Provide the Currency
you want to process payments in. Currently
GBP
for Stripe UK and
USD
for Stripe US are supported.
$.processingPaths.details.secretKey: Make to sure to provide the Stripe Secret Key of your own Stripe Platform Account
and not the Stripe Secret Key of the connected Stripe Account.
$.processingPaths.details.accountId: Provide the Stripe Account ID
of the connected account. You receive the Stripe Account ID from Stripe after successfully performing the OAuth Workflow required for Standalone Accounts or after successful creation of a Managed Account.
$.processingPaths.details.chargeMethod: Provide
DIRECT
to create the charge directly on the connected account.; Provide
THROUGH_PLATFORM
to create the charge on your Stripe Platform account.
$.name: Make sure to specify a unique (internal) name for each merchant that you create.
$.details: Finally, for the payment receipts, you need to provide some information about the merchant, including Public Name, Address and a Contact Phone Number/Email Address
.

You will receive a

merchantIdentifier

after successfully creating the merchant:

Response


{
    "status": "ok",
    "data": {
        /*...*/
        "identifier": "74b47dcd-45b0-4c65-a4d1-afd4aae32708",
        "name": "Stripe Merchant #42"
                /*...*/
    }
}

2. Generate the Merchant Secret Key

Next you can generate a Merchant Secret Key for the Merchant via the API:

post

/v2/merchants/{merchantIdentifier}/secretKey

Try it out!

Request


{
        "permissions": ["READER_MANAGEMENT","TRANSACTIONS"]
}

You will receive the Merchant Secret Key in the response:

Response


{
    "status": "ok",
    "data": {
        "status": "ACTIVE",
        "key": "9pCcTI2mzUbLKoCdezVBowhv0b6gGwoo"
    }
}

Optional: 3. Find the reader you want to assign to the merchant

The platform keeps track of all the readers that you have purchased. In order to assign a reader to the new merchant you have created in Step 1, you must know its

readerIdentifier

. Use this API to find the

readerIdentifier

of a reader based on its serial number (e.g. 999-100001):

get

/v2/readers/?search=999-100001

Try it out!

Request

You will receive the

readerIdentifier

in the response:

Response


{
    "status": "ok",
    "data": [{
        /*...*/
        "identifier": "0665ede3-3990-4c9b-beac-77abfeda5858",
        "model": "MIURA_M010",
        "details": {
            "serialNo": "999100001"
            /*...*/
        }
    }]
}

Optional: 4. Assign the reader to new merchant

Based on the

merchantIdentifier

from Step 1 and the

readerIdentifier

from Step 3, you can now assign the reader to the merchant:

put

/v2/merchants/{merchantIdentifier}/readers/{readerIdentifier}

Try it out!

Request