Appearance
Services on TiruPay Payment Processor
The TiruPay Payment Processor is meant to be used as a gateway. Your service talks to different payment providers through the TiruPay Payment Processor API. Therefore, you need to define your services in the Payment Processor.
A Service represents an application that uses the TiruPay Payment Processor to handle payments on behalf of its users (e.g. easyVerein, software for clubs and associations or TiruPay, a payment single truth solution).
Create a Service
You can use the API or simply login to the TiruPay Payment Processor web interface to create your Service.
When creating a Service, you need to provide the following information:
- Name
- Description
- Force OAuth (if this service should always perform payments on behalf of others)
- Active
Create an API key for your Service
To use the TiruPay Payment Processor API, you need to create an API key for your Service. You can do this in the web interface or via the API.
Select the Service you just created and navigate to the API Keys section. Here, you can create a new API key.
You can activate/deactivate API keys as needed. You see the actual API key only once when creating it. Make sure to store it securely. You can revoke it by generating a new one if needed.
DANGER
Revoking an API key will immediately invalidate it. No payment requests using this API key will work anymore. Make sure to update your applications to use the new API key immediately.
Using the Service API key
When making requests to the TiruPay Payment Processor API, you need to include the API key in the Authorization header.
Example using curl:
bash
curl https://payments.sd-tirupay.de/payments/ \
--request GET \
--header 'Accept: */*' \
--header 'Authorization: Bearer YOUR_API_KEY'Webhooks
You can register webhook URLs for your Service to receive notifications about payment status updates.
To register a webhook, navigate to the Webhooks section of your Service in the web interface and add a new webhook URL. You will receive a secret when creating the webhook, which you can use to verify the authenticity of the webhook requests (see below).
DANGER
Always verify the signature of incoming webhook requests using the provided secret to ensure they are coming from the TiruPay Payment Processor.
Once you have registered a webhook, the TiruPay Payment Processor will send POST requests to the specified URL whenever there is a payment status update or an OAuth event related to your Service (e.g., Onboarding Status changes).
You can invoke a test webhook delivery from the web interface to ensure your webhook endpoint is working correctly.
We log all webhook deliveries and their statuses in the Webhooks section of your Service for easy debugging and monitoring.
INFO
Webhook logs are retained for 30 days. Failed webhooks will not be retried.
Webhook Signature
Webhook requests sent by the TiruPay Payment Processor are signed using the secret that was generated when you created the Webhook. The payload of the webhook is signed using HMAC with SHA256 and the secret as the key. The signature is included in the X-Signature header of the webhook request.
To verify the signature of a webhook request, you can use the following code snippet:
python
import hmac
import hashlib
import json
def sign_payload(payload: dict, secret: str) -> str:
"""
Signs a payload with a secret key.
:param payload: The payload to sign
:param secret: The secret key to sign the payload with
:return: The signed payload as a string
"""
secret = secret.encode('utf-8')
payload_string = json.dumps(payload, sort_keys=True, default=str).encode('utf-8')
signature = hmac.new(secret, payload_string, digestmod=hashlib.sha256).hexdigest()
signature = f"sha256={signature}"
return signature
def verify_signature(payload: dict, secret: str, signature: str) -> bool:
"""
Verifies a payload signature with a secret key.
:param payload: The payload to verify
:param secret: The secret key to verify the payload with
:param signature: The signature to verify against
:return: True if the signature is valid, False otherwise
"""
expected_signature = sign_payload(payload, secret)
return hmac.compare_digest(expected_signature, signature)