Partner Connections

Swap a merchant's one-time code for their API key

The second half of the connection handover.

The merchant authorises your platform inside their SwiftPayIQ portal and is redirected back to you carrying a short-lived code. That code grants nothing on its own — your server swaps it here, authenticated with your partner key, and receives the merchant's own API key in return.

The merchant key is returned exactly once. It is stored hashed and can never be retrieved again, so persist it before you respond to the request. Lose it and the merchant has to authorise you again.

Single use, and codes expire five minutes after they are issued.

A code does not always come back

If the merchant connects a business they already had — rather than one created through the setup page you sent them to — the link is recorded as pending review and waits for a SwiftPayIQ admin to approve it. Their consent is real and dated; what is missing is our decision.

In that case no code is issued, and the merchant returns to your redirect address without a ?code= parameter. This is deliberate: an established merchant's business is not handed to a platform on the strength of one button press.

Handle the no-code return. Treat it as "waiting on SwiftPayIQ", not as a failure and not as a finished connection. Send the merchant back through the setup page and you will get partner.link_already_pending_review — the request is already on file.

post/partner/connections/exchange

Request

  • Base URL: https://api.swiftpayiq.com/api/v1
  • URL: https://api.swiftpayiq.com/api/v1/partner/connections/exchange
  • Auth: HTTP bearer

Request body

codestring required

The one-time code from the merchant redirect.

Example request

{
  "code": "pcc_9f2a7c41e8b3d650"
}

Response

Connected. Store apiKey now — it is never shown again.

apiKeystring

The merchant's API key. Returned once, never retrievable.

businessIdstring
businessNamestring

So you can label the connection in your own interface.

scopesstring[]

Exactly what the merchant agreed to.

Example response

{
  "apiKey": "spi_live_7d3f1a92c4e85b06...",
  "businessId": "biz_2f8a91",
  "businessName": "متجر الأمل",
  "scopes": [
    "payment_links:write",
    "invoices:write",
    "payments:read"
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.