Payment connector - How to configure

On this page you will find how to configure your payment hook and make it usable across all your sales channels — Order In Store, web, marketplace, or any other channel you operate on.

1. Setup the payment connector

Create the payment connector

Call POST /external_payment_providers to declare your connector. Make sure to save the hash_key from the response — it is used to verify the signature of every request OneStock sends to your connector.

POST /external_payment_providers

{
  "site_id": "{{site_id}}",
  "token": "{{token}}",
  "external_payment_provider": {
    "name": "my-psp-connector",
    "url": "https://your-connector-url.com/api/payment",
    "test_url": "https://your-connector-url-dev.com/api/payment",
    "payment_methods": ["pay_by_link", "in_person"],
    "link": {
      "expiration": 3600,
      "format": "qrcode"
    }
  }
}

Response:

{
  "external_payment_provider": {
    "id": "my-psp-connector",
    "hash_key": "{{hash_key}}"
  }
}

A few notes on the parameters:

id — the unique identifier for your connector. This is the key you will use in payment_information when creating orders. Choose a stable, lowercase slug (e.g. my-psp-connector).
url / test_url — production and development endpoints of your connector. We recommend using ngrok for the test URL during development.
name — displayed in the backoffice payment configuration.
image (optional) — base64-encoded image displayed in the Order In Store checkout.
link (optional, Order In Store only) — required for Pay By Link scenarios. Configure:
- expiration — duration in seconds before the link expires
- format — how the link is displayed in the OIS checkout: qrcode, barcode, text, url, or image
- options.barcode.format — if format is barcode, specify the barcode format: CODE128, CODE128A, CODE128B, CODE128C, EAN13, UPC, EAN8, EAN5, EAN2

Declare the payment hook in the payment configuration

This step needs to be done by your OneStock contact.

PATCH /configurations

You have to prefix the name of your connector with "connector-"

{
  "token": "{{token}}",
  "site_id": "{{site_id}}",
  "keys": {
    "payment_v2.available_psps": [
      "connector-my-psp-connector"
    ]
  }
}

2. Edit a payment hook

If your connector URL has changed, update it using PATCH /external_payment_providers/{id}:

PATCH /external_payment_providers/my-psp-connector

{
  "site_id": "{{site_id}}",
  "token": "{{token}}",
  "external_payment_provider": {
    "url": "https://your-new-connector-url.com/api/payment"
  }
}

3. Adding a payment device for your payment hook

To add devices to a payment hook, you can add them through the backoffice stock location pages or by API.

We recommend writing a script to setup payment devices for your project go live and writing a user guide to add payment devices when you open your hook to new stores from the backoffice.

Note: Payment devices (terminals) are required for Order In Store payment flows (direct capture, deferred capture, Pay By Link). For web or marketplace orders using capture and refund via payment_information, no payment device is required — the transaction data is passed directly at order creation.

3.1 Adding payment terminals from the backoffice

Once the connector is setup, the payment terminals can be added for every store directly from your OMC. It is up to the client to correctly setup those terminals depending on the connector specifications:

For a connector implementing direct captures or deferred captures, a POID of the terminal will be required for every store.

For a connector implementing a Pay By Link, you will be creating a virtual terminal.

3.2. Adding payment terminals by API

Create your payment terminals using POST /payments/payment_devices: https://developers.onestock-retail.com/paths/payments-payment_devices/post

4. Limitations

There is no migration between environments, so when going live you'll have to create the hook and declare it in production. Make sure to write step by step go live manipulations for go live:

Create payment hook
Share hash so that the responsible for hosting your payment hook updates the value to be checked and use in production
Declare the hook in production
Run a script to setup the payment terminals for the correct stores (Order In Store flows only)
Create an order using your hook in production