Skip to main content

Secret Key and Notification URL

This guide explains how to retrieve the merchant's Secret Key and configure the URL used by Orkestral to send transaction updates.

The notification URL works as the client's webhook.

Before you begin​

To complete the configuration, you must:

  • have an active Orkestral account;
  • have access to the management platform;
  • be linked to the merchant that will be configured;
  • have a public and accessible URL to receive notifications.

Access the integration settings​

  1. Access the Orkestral platform.
  2. In the side menu, click Integration.
  3. Enter your user password again.
  4. Click Submit.

After validating the password, the platform displays the Secret Key and the notification URL settings.

Secret Key​

What is the Secret Key?​

The Secret Key is a credential associated with the merchant. It is generated automatically when the merchant is created and is shared by the users linked to that merchant. Therefore, a different key is not created for each platform user.

Orkestral uses this key to generate the checksum included in transaction notifications. The client can use the key to validate the authenticity of received notifications according to the API integration contract.

info

The Secret Key displayed on this page does not replace the access token used for API calls. Orkestral API authentication uses OAuth and JWT tokens.

Retrieve the Secret Key​

  1. Open the Integration menu.
  2. Enter your user password again.
  3. Find the Secret Key section.
  4. Use the copy button to copy the displayed value.
  5. Store the key in a secure location.

Protect the Secret Key​

  • Do not share the key by email, messages, or public channels.
  • Do not store the key directly in source code.
  • Do not expose the key in frontend applications.
  • Do not write the key to logs.
  • Use a secrets manager or a protected environment variable.
  • Restrict access to the services responsible for validating notifications.
warning

The platform does not provide key regeneration or rotation through the interface. If the key is exposed or compromised, contact the team responsible for Orkestral.

Notification URL​

What is the Notification URL?​

The notification URL is the address Orkestral uses to inform the client about transaction updates.

For example, a notification may be sent when a transaction is approved, denied, settled, or has another relevant status change.

Orkestral sends an HTTP POST request with JSON content to the selected URL.

Register the URL​

  1. Open the Integration menu.

  2. Enter your user password again if requested.

  3. Find the URL section.

  4. Enter the full webhook address, for example:

    https://api.example.com/webhooks/orkestral

  5. Click the confirmation button to save.

  6. Verify that the registered URL was updated correctly.

The URL should:

  • be public and accessible over the internet;
  • use HTTPS;
  • accept HTTP POST requests;
  • accept application/json content;
  • return a successful 2xx HTTP status;
  • process notifications idempotently;
  • validate the received checksum;
  • not depend on an authenticated browser session;
  • be monitored for failures and downtime.
note

Although HTTPS is recommended to protect transmitted data, the current interface does not explicitly validate the submitted protocol.

Default URL and per-transaction URL​

Orkestral allows the notification URL to be defined on the merchant or directly on the transaction.

URL registered on the merchant​

The URL registered on the Integration page works as the merchant's default webhook. It is used when a transaction does not have a specific URL.

URL provided in the transaction​

When creating a transaction, the client can also provide the webhook_url field:

{
  "webhook_url": "https://api.example.com/webhooks/transaction"
}

When this field is provided, its URL is used for the corresponding transaction.

Priority order​

Orkestral applies the following order:

  1. the webhook_url provided when the transaction is created;
  2. the URL registered on the merchant through the Integration page.

If neither URL is configured, Orkestral will not have a valid destination for delivering the notification to the client.

Notification content​

The notification may contain information such as:

  • merchant identifier;
  • transaction identifier;
  • amount and currency;
  • transaction country;
  • payment method;
  • event identifier;
  • event name or status;
  • message returned by the payment service provider;
  • security checksum.

Illustrative example:

{
  "merchantId": "00000000-0000-0000-0000-000000000000",
  "transactionId": "11111111-1111-1111-1111-111111111111",
  "amount": 10000,
  "currency": "BRL",
  "country": "BR",
  "paymentMethod": "PIX",
  "eventId": 12345,
  "eventName": "APPROVED",
  "pspMessage": "Transaction approved",
  "checksum": "checksum-value"
}

The fields sent may vary depending on the transaction type, payment method, and processed event.

Validate notifications​

When receiving a notification, the client should:

  1. validate that the request has the expected format;
  2. use the merchant's Secret Key to validate the checksum;
  3. check whether the event has already been processed;
  4. record the transaction update idempotently;
  5. return a 2xx HTTP status when the notification is processed;
  6. return an error HTTP status when the notification cannot be processed.

Validating the checksum helps confirm that the notification was generated by Orkestral and that the data used in the signature is consistent.

Best practices​

  • Use different endpoints for testing and production environments.
  • Do not use local URLs such as localhost.
  • Keep the HTTPS certificate valid.
  • Respond quickly and process long-running tasks asynchronously.
  • Implement idempotency using the transaction and event identifiers.
  • Monitor HTTP errors, response time, and downtime.
  • Protect the Secret Key with a secrets manager.
  • Do not confuse the Secret Key used to validate notifications with the API authentication credentials.