Lynk setup

Lynk is a Jamaican mobile wallet. With Genius Checkout, the buyer enters their Lynk ID, receives a payment request in the Lynk mobile app, and approves or rejects it there.

Lynk does not collect card details and is not a card gateway.

Capabilities and limitations

Capability	Genius Checkout support
Currency	JMD only
Buyer flow	Push-to-app approval using the buyer's Lynk ID
Authorize Only	Not supported
Authorize & Capture	Lynk is sale-only; funds are transferred after the buyer approves
Status updates	Lynk webhook, with status polling as a fallback
Refunds	Initiated manually in the LynkBiz Merchant Portal
Partial refunds	Not supported by the current Lynk integration
Void	Not supported
3-D Secure	Not applicable
Recurring payments	Scheduled payment request; the buyer must approve every renewal in the Lynk app

Buyer approval is always required

A Lynk subscription is not a silent card-on-file charge. Genius Checkout sends a new request to the saved Lynk ID for each billing cycle, and the buyer must approve it in the app.

Get a LynkBiz merchant account

Register through Lynk for Business and ask Lynk to enable eCommerce / Pay with Lynk API access.

For the integration, Lynk normally provides:

• the Pay with Lynk API guide and OpenAPI contract;
• separate Test and Production environments;
• a Client ID and Client Secret for each environment;
• the environment URLs and LynkBiz Merchant Portal access;
• sandbox Lynk IDs or consumer accounts for testing.

Lynk may ask you to provide:

• your public store domain;
• the Genius Checkout notification URL: https://app.geniuscheckout.com/webhooks/lynk;
• a strong Webhook Shared Secret that both Lynk and Genius Checkout will use.

Ask Lynk to confirm that the OAuth client is provisioned for online payments. A valid token must contain the Lynk API-key claim used by the payment API.

Credential mapping

Open Gateways, choose Lynk, and click Configure.

Complete the Test and Live credential cards independently:

Genius Checkout field	Enter this	Source
Lynk Client ID	OAuth2 Client ID for the selected environment	Lynk onboarding
Lynk Client Secret	Client Secret paired with that Client ID	Lynk onboarding
Webhook Shared Secret	The exact secret registered with Lynk for webhook signing	Agreed with Lynk
Accepted currencies	JMD only	Fixed by the Lynk integration

Do not enter a Lynk username, merchant-portal password, access token, or API key into the Client ID or Client Secret fields. Genius Checkout exchanges the OAuth credentials for an access token and extracts the required API key automatically.

Keep Test and Live separate

Test credentials authenticate only against the Lynk sandbox. Production credentials authenticate only against Lynk's live environment. Do not copy one credential pair into both cards.

Payment timeout

Payment timeout (seconds) controls how long Genius Checkout waits for the buyer to approve the request in the Lynk app.

• Default: 300 seconds (5 minutes)
• Minimum: 5 seconds
• Maximum: 1800 seconds (30 minutes)

Five minutes is appropriate for most stores. A shorter timeout can frustrate buyers who need time to find and open the app. A very long timeout keeps abandoned checkouts pending longer.

Webhook configuration

Give Lynk this notification URL for both environments:

https://app.geniuscheckout.com/webhooks/lynk

The value in Webhook Shared Secret must exactly match the secret Lynk uses to create the x-signature HMAC-SHA256 header.

The webhook communicates these outcomes:

Lynk outcome	Meaning in Genius Checkout
received	Request sent; awaiting buyer action
paid	Buyer approved and funds were credited
failed	Buyer approved, but the transfer failed
rejected	Buyer declined the request
refunded	A previously paid transaction was refunded through Lynk

Genius Checkout also checks the order status through Lynk's API, so a delayed webhook does not automatically mean the payment is lost.

Test the connection

1. Enter and save the Test Client ID and Client Secret.
2. Enable Test mode and select only JMD.
3. Click Test Connection.
4. Genius Checkout performs the OAuth client-credentials exchange and verifies that the returned token contains Lynk's required API-key claim.

The connection test does not create a payment request or move money.

If Lynk provided the standard simulated sandbox users, test each applicable result:

Sandbox Lynk ID	Expected result
@lynkbiz-pay	Approved within approximately 30 seconds
@lynkbiz-reject	Rejected within approximately 30 seconds
@lynkbiz-timeout	Times out
@lynkbiz-delayed-pay	Delayed approval
@lynkbiz-delayed-reject	Delayed rejection
@lynkbiz-delayed-timeout	Delayed timeout

Use only the test identities supplied or approved by Lynk. Their sandbox account names can change between onboarding programmes.

Buyer experience

1. The buyer selects Lynk on the Genius Checkout page.
2. They enter the Lynk ID from their mobile app.
3. Genius Checkout sends the payment request to Lynk.
4. The buyer opens the Lynk app and approves or rejects it.
5. The checkout updates automatically after Lynk confirms the result.

If the buyer does nothing, Genius Checkout stops waiting when the configured payment timeout is reached.

Refund a Lynk payment

The current Lynk API does not expose a programmatic refund operation to Genius Checkout.

1. Open the captured transaction in Genius Checkout.
2. Use the Open Lynk portal action shown in the manual-refund panel.
3. Find the matching payment in the LynkBiz Merchant Portal.
4. Issue the refund according to Lynk's portal process.
5. Wait for Lynk to confirm the updated status.

Do not use Void for Lynk. An unapproved request simply expires or is rejected; an approved payment must be handled through the portal.

Go live

1. Complete Lynk's required sandbox scenarios.
2. Provide any integration evidence requested by Lynk.
3. Obtain the separate Production Client ID and Client Secret.
4. Confirm the live webhook URL and shared secret with Lynk.
5. Add the credentials to the Live card and select only JMD.
6. Click Test Connection for Live.
7. Process a low-value real payment using a Lynk account you control.
8. Confirm the payment in Genius Checkout and the LynkBiz Merchant Portal.
9. Test the manual refund process.

Troubleshooting

Symptom	Check
Invalid client / access denied	Client ID and Client Secret must belong to the same environment, and Lynk must authorize the client for online payments.
Token issued but API-key claim missing	Ask Lynk to provision the OAuth client for Pay with Lynk online payments.
Payment rejected before sending	The checkout currency must be JMD and the buyer must enter a valid Lynk ID.
Buyer gets no app notification	Confirm the Lynk ID, sandbox identity, and that the buyer is signed into the correct Lynk app environment.
Payment remains pending	Check the timeout, Lynk order status, webhook secret, and whether the notification URL was registered.
Webhook returns 401	The Webhook Shared Secret in Genius Checkout does not match Lynk's signing secret.
Refund button is unavailable	Lynk refunds are initiated in the LynkBiz Merchant Portal, not through the API.

Related guides

• Adding a Gateway
• Test vs Live Credentials
• Subscriptions Overview
• Issuing Refunds

Provider references

• Lynk for Business
• Lynk support