Get started

Set up your store, keep your keys safe and check that you receive webhooks.

Set up your store with POST /v1/setup and save the keys in the response.
Keep the secret key on your server and use the publishable key on your page.
Send a test webhook to your endpoint.

Setup is the only call without a secret key. Use the client id and client secret of your n1co Integration API application:

Set up the store

curl -s -X POST https://api-epay.dev.n1co.dev/v1/setup \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<your application client id>",
    "client_secret": "<your application client secret>",
    "webhook_url": "https://hooks.example.com/n1co"
  }'

201 Created

{
  "store_id": "0b9f8a52-2f0e-4d84-9a52-6c1f7e0d9a11",
  "store_name": "Example Store",
  "publishable_key": "pk_3x4mpl3pUbl1shabl3k3yAAAAAAAAAAA",
  "secret_key": "sk_3x4mpl3s3cr3tk3yAAAAAAAAAAAAAAAA",
  "webhook": {
    "url": "https://hooks.example.com/n1co",
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
  }
}

Keys#

Key	Format	Where it is used
`publishable_key`	`pk_` and 32 characters	On your page: `n1co('pk_…')`. It is public.
`secret_key`	`sk_` and 32 characters	On your server: `Authorization: Bearer sk_…`.
`webhook.secret`	`whsec_` and 32 characters	On your server, to verify webhooks.

Each card session and each payment intent also comes with a client_secret. Your server hands it only to that buyer's page.

An authenticated call

curl -s 'https://api-epay.dev.n1co.dev/v1/events?limit=1' \
  -H "Authorization: Bearer $N1CO_SECRET_KEY"

Without a valid key, the response is 401 invalid_api_key.

Your application and the environments#

Your Integration API application must belong to your store and have the EPay.ReadWrite.OwnedBy and Store.Read.OwnedBy roles. ePay uses the client secret only in that call and does not store it.

The first setup can take about a minute: use a timeout of at least two minutes.

Environment	ePay API	n1co.js
Development	`https://api-epay.dev.n1co.dev`	`https://elements.n1co.dev/v1/n1co.js`
Production	To be announced	To be announced

Each environment has its own setup and its own keys.

Changing the setup#

Repeat POST /v1/setup to change anything. It is idempotent and always verifies your application again.

If you send	Response
The same as the current setup	`409 store_already_enabled`, no secrets
A different `webhook_url`	`200` with a new `webhook.secret`
`"rotate_secret_key": true`	`200` with a new `secret_key`
`"rotate_webhook_secret": true`	`200` with a new `webhook.secret`
A different `client_id`	`200`, bound to the new application

A rotated key replaces the previous one as soon as the response arrives: deploy it right away. The publishable key is not rotated. The error codes are in Errors.

The webhook URL#

It uses https, has no user, password or fragment, and is at most 2048 characters long.
Its host is a public name or IP: localhost, *.local, *.internal and single-label names are not accepted.
Every address it resolves to must be public.

Otherwise, the response is 400 invalid_request.

Check the connection#

POST /v1/webhooks/test sends a signed webhook.test event to your webhook_url:

curl -s -X POST https://api-epay.dev.n1co.dev/v1/webhooks/test \
  -H "Authorization: Bearer $N1CO_SECRET_KEY"

It responds 202. To verify the signature, continue with Webhooks; for your first integration, with Save a card.