POST
/
api
/
webhook
/
merchant
  curl --request POST \
  --url https://api.atoa.me/api/webhook/merchant \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://api/endpoint",
  "event": "PAYMENTS_STATUS, EXPIRED_STATUS or REFUND_STATUS"
}'

{
  "webhookId": "4a124f25-fe8d-47a0-92c8-16d94cbfe24c",
  "url": "https://example.com",
  "event": "PAYMENTS_STATUS, EXPIRED_STATUS or REFUND_STATUS"
}

Generate a webhook event for a specific endpoint . Atoa utilizes webhooks to instantly alert your application, which is particularly valuable for asynchronous events, such as updates on payment transaction status, including completion, failure, or pending. Begin by generating a webhook event for a specific endpoint.

  • Default - No additional auth

  • OAuth Authentication

  • Basic Authentication

cURL
curl --request POST \
--url https://api.atoa.me/api/webhook/merchant \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://example.com",
"event": "PAYMENTS_STATUS, EXPIRED_STATUS or REFUND_STATUS"
}'

Security is crucial when implementing webhooks. Atoa provides three authentication methods to ensure your webhook endpoints are secure and only process legitimate requests:

1. Signature Verification

Every webhook request includes a signature in the response that allows you to verify the authenticity of the request. This is a cryptographic signature generated using your webhook secret and the request payload. This method is:

  • Secure: Validates that requests genuinely come from Atoa
  • Lightweight: Doesn’t require additional parameters when creating the webhook
  • Stateless: No need to manage tokens or credentials

To verify the signature, refer the docs here

Signature verification requires implementation on your server. Your endpoint should extract the signature from the response and validate it against your webhook secret. This is essential for all webhooks to ensure they originated from Atoa.

2. OAuth 2.0 Authentication

For enhanced security, you can configure your webhook to use OAuth 2.0 authentication. When this is enabled:

  • Atoa will automatically obtain access tokens from your authorization server
  • These tokens are included in webhook requests to your endpoint
  • Your application can validate these tokens with your OAuth provider

This provides an additional layer of security and integrates with existing OAuth infrastructure.

3. Basic Authentication

If you prefer a simpler approach, you can use HTTP Basic Authentication:

  • Configure your webhook with a username and password
  • Atoa will include these credentials in the Authorization header of webhook requests
  • Your endpoint can validate these credentials before processing the webhook

This option is straightforward to implement while still providing protection against unauthorized requests.

Signature verification provides strong security and is our recommended approach for webhook authentication. It cryptographically verifies that requests come from Atoa. Using OAuth or Basic Authentication alone provides a different security layer but may be less secure than signature verification. For maximum security, consider combining signature verification with either OAuth or Basic Authentication.

If you don’t specify either OAuth or Basic Authentication when creating your webhook, you’ll need to rely solely on signature verification for security.

​
Webhook Retry Mechanism

When a webhook response is anything other than HTTP 200, it is considered a failure. When this happens, our system uses a retry mechanism, following an exponential back-off strategy. If the webhook continues to fail over 24 hours, Atoa will stop the retry attempts. In these scenarios, we will send an email notification to the business owner with relevant information, including the webhook URL.

​
Webhook Subscription Guide

To stay updated on the status of payments, subscribe to our webhook with the appropriate event types.

  • PAYMENT_STATUS: Receive webhook payloads for successful, pending, and failed payments.
  • EXPIRED_STATUS: Receive webhook payloads for expired payments.
  • REFUND_STATUS: Receive webhook notifications when refunds are processed. You’ll be notified for the following refund statuses:
    • COMPLETED: Refund has been successfully processed
    • CANCELLED: Refund request was cancelled
    • FAILED: Refund processing failed

The payment will expire after the time specified in the expiresIn parameter when generating the payment request.

Refer to the refunds API for more information on refunds.

Ensure your webhook listener is setup to handle these payloads and process the events accordingly.

​
Authorization

Bearer <token>

Request Body Schema

url
string
required

Merchant webhook url provided will receive notification on status code 200 and will be retried on failure.

event
string
required

Event subscribed to which the webhook will be invoked.

authentication
object

Optional authentication configuration for securing your webhook endpoint. Choose one method that best matches your security requirements.

authentication
object

Optional authentication configuration for securing your webhook endpoint. Choose one method that best matches your security requirements.

Response

webhookId
string

A unique identifier for the created webhook.

url
string

The URL that will receive the webhook notifications.

event
string

The type of event subscribed to for webhook notifications (e.g., PAYMENT_STATUS, EXPIRED_STATUS, REFUND_STATUS).

Get List of Available Institutions or BanksGet all merchant webhooks