Appearance
Payments
This section provides an overview on how to process payments using the TiruPay Payment Processor microservice.
INFO
In the following example, we will create a single, one-time payment using no mandates. Further down on this page, we explain how to create recurring payments using mandates.
1. Create / Update Customer
First, you need to tell the Payment Processor about your customer. You can create or update a customer using the following endpoint:
Not all fields are transported to all payment providers, but it always makes sense to keep as much data as possible in the Payment Processor.
bash
curl https://payments.sd-tirupay.de/customers/ \
--request POST \ // Updates take PATCH and the customer_id in the URL
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY' \
--data '{
"first_name": "Max Jason",
"last_name": "Mustermann",
"email": "mm@software-design.de",
"phone": "+49123789123789",
"currency": "EUR",
"street": "Acme Street 1",
"city": "Freiburg",
"postal_code": "79111",
"country": "Germany",
"country_code": "DE",
"service_upi": "TSimon_user_1"
}'python
import requests
requests.post( # Use requests.patch() for updates and include the customer_id in the URL
"https://payments.sd-tirupay.de/customers/",
headers={
"Accept": "*/*",
"Content-Type": "application/json",
"Authorization": "Bearer API_KEY"
},
json={
"first_name": "Max Jason",
"last_name": "Mustermann",
"email": "mm@software-design.de",
"phone": "+49123789123789",
"currency": "EUR",
"street": "Acme Street 1",
"city": "Freiburg",
"postal_code": "79111",
"country": "Germany",
"country_code": "DE",
"service_upi": "TSimon_user_1",
"is_company": False
}
)You will receive the created / updated customer object in the response. It includes an id field which is the customer_id you will use in the next steps.
2. Create Payment
WARNING
If you are processing payments on behalf of a partner (Partner OAuth), you need to include the partner_upi field in the payment creation request to specify which partner the payment is for. See the Partner OAuth Documentation for more details.
If no partner_upi is provided, the payment will be processed using the service's own payment provider credentials.
Next, create a payment object with the details you already know. This payment object is only stored on TiruPay Payment Processor for now.
bash
curl 'https://payments.sd-tirupay.de/payments/?service_id=SERVICE_ID' \
--request POST \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY' \
--data '{
"amount": 42,
"currency": "EUR",
"description": "A simple payment",
"service_upi": "PAYMENT_SERVICE_ID_1",
"invoice_number": "INVOICE_NUMBER_12345",
"service_id": "SERVICE ID",
"partner": "mollie",
"customer_id": "CUSTOMER_ID",
"final_redirect_url": "http://localhost:9000/final_payment_redirect",
"checkout_mode": "partner_hosted_checkout",
"capture_mode": "automatic",
"service_metadata": {
"propertyName*": "anything"
},
}'python
import requests
requests.post(
"https://payments.sd-tirupay.de/payments/",
headers={
"Accept": "*/*",
"Content-Type": "application/json",
"Authorization": "Bearer API_KEY"
},
params={
"service_id": "SERVICE_ID"
},
json={
"amount": 42,
"currency": "EUR",
"description": "A simple payment",
"service_upi": "PAYMENT_SERVICE_ID_1",
"service_id": "SERVICE ID",
"invoice_number": "INVOICE_NUMBER_12345",
"partner": "mollie",
"customer_id": "CUSTOMER_ID",
"final_redirect_url": "http://localhost:9000/final_payment_redirect",
"checkout_mode": "partner_hosted_checkout",
"capture_mode": "automatic",
"service_metadata": {
"propertyName*": "anything"
},
}
)You will receive the created payment object in the response. It includes an id field which is the payment_id you will use in the next step.
You can send different capture_mode and checkout_mode values depending on your use case and the payment provider capabilities.
Description and Invoice Number
description is the text the customer sees as payment reference, e.g. on a SEPA direct debit or bank statement. Set invoice_number to the number of the invoice this payment settles: it is forwarded to Nemo and stored in the Mollie payment's metadata (tirupay_invoice_number). If you omit description, Mollie gets <service name> - <invoice_number> as reference. Set both before selecting the payment: changes made afterwards are not passed on to the partner.
Capture Modes
automatic: The payment will be captured automatically once the user completes the payment.manual: The payment will need to be captured manually via the Payment Processor API after the user completes the payment.
Checkout Modes
partner_hosted_checkout: The user will be redirected to the payment provider's hosted checkout page to complete the payment.self_hosted_checkout: The payment will be completed using your frontend. If you need more informations, the select payment step will provide them. Once you acquired them, select the payment again with the necessary data to complete the payment.mandate: The payment will be processed using a previously created mandate. See the Mandates Section for more details. The user will not be redirected as this is a backend/background operation.
3. Select Payment and Complete Checkout
Now, you need to select the payment to create the payment in the respective payment provider (Mollie / Stripe) and get the payment URL or client secret to complete the payment.
If you are using partner_hosted_checkout, redirect the user to the provided payment URL.
If you are using self_hosted_checkout, use the provided client secret to complete the payment in your frontend (or request it). If you are using mandate, the payment will be processed in the background without user interaction.
Depending on the mode you selected, the request parameters and response will vary. In this example, we are using partner_hosted_checkout.
bash
curl 'https://payments.sd-tirupay.de/payments/by_id/{our_id}/select?partner=mollie&capture_mode=automatic&payment_method=credit_card&checkout_mode=partner_hosted_checkout&partner_mandate_id=&mollie_card_token=' \
--request POST \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.post(
"https://payments.sd-tirupay.de/payments/by_id/{our_id}/select",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
},
params={
"partner": "mollie",
"capture_mode": "automatic",
"payment_method": "credit_card",
"checkout_mode": "partner_hosted_checkout",
"partner_mandate_id": "",
"mollie_card_token": ""
}
)We told Mollie to use credit card as the payment method in this example. Depending on the payment provider and the selected payment method, you might need to provide additional parameters (like a card token). You can also leave out the payment_method parameter to let the user select their preferred payment method in the hosted checkout. You will receive a response containing the payment URL to redirect the user to complete the payment (redirect_url).
4. Handle Redirect and Webhooks
Redirect the user to the payment URL. Once they are done, the TiruPay Payment Processor will redirect them to the defined final_redirect_url with the payment_id as a query parameter.
The TiruPay Payment Processor will also send webhook notifications to your specified webhook URL to inform you about payment status updates. You can always fetch the current state of a payment via the API.
bash
curl https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.get(
"https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
}
)You will receive the payment object in the response, which includes the current status of the payment.
Payment Statuses
INFO
The status of a payment is never finalized. It can change over time based on user actions and payment provider updates. E.g. a payment can be open, then pending, then paid, and 50 days later charged_back.
The payment can have the following statuses:
open: The payment has been created. If no partner_id is assigned yet, the payment is not yet selected.pending: The payment is in progress (e.g. waiting for user to complete payment).paid: The payment has been successfully completed.failed: The payment has failed.canceled: The payment has been canceled.user_interaction_needed: The payment requires further user interaction to complete (e.g. 3D Secure authentication).ready_for_capture: The payment is authorized and ready to be captured (only for manual capture mode).refunded: The payment has been refunded.charged_back: The payment has been charged back.
Not all statuses are available on all payment providers. Mollie, for example, does not have a user_interaction_needed status.
Using Mandates for Recurring Payments
Mandates allow you to process recurring payments without requiring user interaction for each payment. You can create a mandate for a customer and then use that mandate to process subsequent payments.
WARNING
Mandates are only supported by certain payment providers and certain payment methods. Make sure to check the capabilities of your chosen payment provider.
SEPA Debit Mandates with Mollie
If you want to create a SEPA Debit mandate with Mollie, you need to follow these steps:
1. Create a Mandate
Use our API to create a mandate for your customer with CUSTOMER_ID.
WARNING
If you want to create mandates on behalf of a partner (Partner OAuth), you need to include the partner_oauth_id (our ID for the partner_oauth object) field in the mandate creation request to specify which partner the mandate is for.
bash
curl 'https://payments.sd-tirupay.de/customers/by_id/CUSTOMER_ID/mandates?partner=mollie&partner_oauth_id=PARTNER_OAUTH_ID&payment_method=sepa_direct_debit&sepa_mandate_reference=UNIQUE_ABC_12345&sepa_signature_date=2025-12-02&sepa_customer_bic=INGDDEFFXXX&sepa_customer_iban=DE98500105174897132186&paypal_billing_agreement_id=&paypal_vault_id=' \
--request POST \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.post(
"https://payments.sd-tirupay.de/customers/by_id/CUSTOMER_ID/mandates",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
},
params={
"partner": "mollie",
"partner_oauth_id": "PARTNER_OAUTH_ID",
"payment_method": "sepa_direct_debit",
"sepa_mandate_reference": "UNIQUE_ABC_12345",
"sepa_signature_date": "2025-12-02",
"sepa_customer_bic": "INGDDEFFXXX",
"sepa_customer_iban": "DE98500105174897132186",
"paypal_billing_agreement_id": "",
"paypal_vault_id": ""
}
)You will receive a mandate ID in the response. The mandate, depending on the payment provider, might need to be activated by the customer (e.g. via a signed document or email confirmation).
2. Validate Mandate Status
You can always fetch the mandates of a customer to check their status.
bash
curl 'https://payments.sd-tirupay.de/customers/by_id/CUSTOMER_ID/mandates?partner=mollie&partner_oauth_id=PARTNER_OAUTH_ID' \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.get(
"https://payments.sd-tirupay.de/customers/by_id/CUSTOMER_ID/mandates",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
},
params={
"partner": "mollie",
"partner_oauth_id": "PARTNER_OAUTH_ID"
}
)You will receive a list of mandates in the response. Check the mandate_status field of the mandate to ensure it is active before using it for payments.
The available states are:
pending: The mandate is created but not yet active.active: The mandate is active and can be used for payments.unavailable: The mandate cannot be used.
If you want to know the exact status of the payment provider, look in the field partner_status.
3. Create Payments Using the Mandate
When creating a payment, you need to specify the partner_mandate_id parameter with the mandate ID you received earlier at the latest when selecting the payment. And, of course, use the mandate checkout mode and correct payment method.
You can also set the subscription field to true and pass along a subscription_id to link the payment to a subscription object on your service. Both are optional in this case.
bash
curl 'https://payments.sd-tirupay.de/payments/?service_id=SERVICE_ID' \
--request POST \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY' \
--data '{
"amount": 42,
"currency": "EUR",
"description": "A simple recurring payment",
"service_upi": "PAYMENT_SERVICE_ID_1",
"invoice_number": "INVOICE_NUMBER_12345",
"service_id": "SERVICE ID",
"partner": "mollie",
"customer_id": "CUSTOMER_ID",
"final_redirect_url": "http://localhost:9000/final_payment_redirect",
"checkout_mode": "mandate",
"capture_mode": "automatic",
"subscription": true,
"subscription_service_upi": "SUBSCRIPTION_UPI_1",
"service_metadata": {
"propertyName*": "anything"
},
}'python
import requests
requests.post(
"https://payments.sd-tirupay.de/payments/",
headers={
"Accept": "*/*",
"Content-Type": "application/json",
"Authorization": "Bearer API_KEY"
},
params={
"service_id": "SERVICE_ID"
},
json={
"amount": 42,
"currency": "EUR",
"description": "A simple recurring payment",
"service_upi": "PAYMENT_SERVICE_ID_1",
"invoice_number": "INVOICE_NUMBER_12345",
"service_id": "SERVICE ID",
"partner": "mollie",
"customer_id": "CUSTOMER_ID",
"final_redirect_url": "http://localhost:9000/final_payment_redirect",
"checkout_mode": "mandate",
"capture_mode": "automatic",
"subscription": True,
"subscription_service_upi": "SUBSCRIPTION_UPI_1",
"service_metadata": {
"propertyName*": "anything"
},
}
)You will receive the created payment object in the response. It includes an id field which is the payment_id you will use in the next step.
4. Select Payment Using the Mandate
As we have not provided the partner_mandate_id when creating the payment, we need to provide it now when selecting the payment.
bash
curl 'https://payments.sd-tirupay.de/payments/by_id/{our_id}/select?partner=mollie&capture_mode=automatic&payment_method=sepa_direct_debit&checkout_mode=mandate&partner_mandate_id=MANDATE_ID&mollie_card_token=' \
--request POST \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.post(
"https://payments.sd-tirupay.de/payments/by_id/{our_id}/select",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
},
params={
"partner": "mollie",
"capture_mode": "automatic",
"payment_method": "sepa_direct_debit",
"checkout_mode": "mandate",
"partner_mandate_id": "MANDATE_ID",
"mollie_card_token": ""
}
)This will not return a redirect URL as the payment is processed in the background using the mandate.
You will be informed about the payment status via webhooks or by querying the payment status via the API as described in step 4 of the main payment flow.
TIP
You can reuse the mandate for future payments without needing to create a new mandate each time.
Credit Card Mandates using Mollie
WARNING
If you want to create mandates on behalf of a partner (Partner OAuth), you need to include the partner_oauth_upi (your ID for the partner_oauth object) field in the payment creation request to specify which partner the mandate is for.
Now credit card mandates are also supported, but they are created during the payment process, as credit card mandates need a successful payment first.
In our example, we want to create a mandate for a subscription and we acquire the mandate during the first monthly payment.
1. Create Payment for Subscription with Credit Card Mandate
As we need to acquire the mandate during the payment process and have to inquire our user to provide us the fields, we create a payment with checkout_mode set to partner_hosted or self_hosted_checkout and payment_method set to credit_card.
bash
curl 'https://payments.sd-tirupay.de/payments/?service_id=SERVICE_ID' \
--request POST \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY' \
--data '{
"amount": 10,
"currency": "EUR",
"description": "First payment for subscription with credit card mandate",
"service_upi": "PAYMENT_SERVICE_ID_1",
"service_id": "SERVICE ID",
"partner": "mollie",
"customer_id": "CUSTOMER_ID",
"final_redirect_url": "http://localhost:9000/final_payment_redirect",
"checkout_mode": "partner_hosted_checkout",
"capture_mode": "automatic",
"subscription": true,
"subscription_service_upi": "SUBSCRIPTION_UPI_1",
"service_metadata": {
"propertyName*": "anything"
},
}'python
import requests
requests.post(
"https://payments.sd-tirupay.de/payments/",
headers={
"Accept": "*/*",
"Content-Type": "application/json",
"Authorization": "Bearer API_KEY"
},
params={
"service_id": "SERVICE_ID"
},
json={
"amount": 10,
"currency": "EUR",
"description": "First payment for subscription with credit card mandate",
"service_upi": "PAYMENT_SERVICE_ID_1",
"service_id": "SERVICE ID",
"partner": "mollie",
"customer_id": "CUSTOMER_ID",
"final_redirect_url": "http://localhost:9000/final_payment_redirect",
"checkout_mode": "partner_hosted_checkout",
"capture_mode": "automatic",
"subscription": True,
"subscription_service_upi": "SUBSCRIPTION_UPI_1",
"service_metadata": {
"propertyName*": "anything"
},
}
)You will receive the created payment object in the response. It includes an id field which is the payment_id you will use in the next step.
2. Select Payment to Acquire Mandate
When selecting the payment, make sure to provide payment_method as credit_card. This will ensure that Mollie creates a credit card mandate during the payment process.
bash
curl 'https://payments.sd-tirupay.de/payments/by_id/{our_id}/select?partner=mollie&capture_mode=automatic&payment_method=credit_card&checkout_mode=partner_hosted_checkout&partner_mandate_id=&mollie_card_token=' \
--request POST \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.post(
"https://payments.sd-tirupay.de/payments/by_id/{our_id}/select",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
},
params={
"partner": "mollie",
"capture_mode": "automatic",
"payment_method": "credit_card",
"checkout_mode": "partner_hosted_checkout",
"partner_mandate_id": "",
"mollie_card_token": ""
}
)You will receive a response containing the payment URL to redirect the user to complete the payment (redirect_url).
3. Handle Redirect and Webhooks
Redirect the user to the payment URL. Once they are done, the TiruPay Payment Processor will redirect them to the defined final_redirect_url with the payment_id as a query parameter.
The payment object, if successful, will now include a partner_mandate_id field with the created mandate ID. And, if you ask for the mandates of the customer, you will see the newly created credit card mandate with status active.
You will be informed about the payment status via webhooks or by querying the payment status via the API as described in step 4 of the main payment flow.
4. Use Mandate for Subsequent Payments
You can now use the created credit card mandate for subsequent payments without requiring user interaction.
When creating a new payment, specify the partner_mandate_id parameter with the mandate ID you received earlier at the latest when selecting the payment.
Set the checkout_mode to mandate and the payment_method to credit_card.
Refunding Payments
You can refund paid payments. Payment refunds can be full or partial. Note that a refund might take some time to be processed depending on the payment provider, invoke optional transaction costs and might not be possible for certain payment methods. You need to provide a description for the refund.
Use the following endpoint:
bash
curl 'https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID/refund?description=THE%20NECESSARY%20DESCRIPTION%20OF%20THE%20REFUND&amount=20.00¤cy=EUR' \
--request POST \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.post(
"https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID/refund",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
},
params={
"description": "THE NECESSARY DESCRIPTION OF THE REFUND",
"amount": "20.00", # Optional, omit for full refund
"currency": "EUR" # Must be the same as the original payment currency
}
)As the payment processor does not differentiate between partial and full refunds, the payment will move into refunded state once the refund is successful.
You can request all refunds of a payment using the respective endpoint (/payments/by_id/PAYMENT_ID/refunds).
Cancel Payments
You can cancel open or pending payments and ready_for_capture payments (only in manual capture mode).
Use the following endpoint:
bash
curl 'https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID/cancel' \
--request POST \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.post(
"https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID/cancel",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
}
)This will cancel the payment if possible. You will receive the updated payment object in the response.
Capture Payments
You can capture ready_for_capture payments (only in manual capture mode).
While some payment providers allow multiple captures, most only allow a single capture per payment.
Use the following endpoint:
bash
curl 'https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID/capture?amount=20.00¤cy=EUR' \
--request POST \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.post(
"https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID/capture",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
},
params={
"amount": "20.00", # Optional, omit for full capture
"currency": "EUR" # Must be the same as the original payment currency
}
)Depending on the payment provider and payment method, the payment might move back into pending state after capture and only later into paid state once the capture is fully processed.
You can request all captures of a payment using the respective endpoint (/payments/by_id/PAYMENT_ID/captures).
Free (Remaining) Capture Amount / Release Authorization
You can free the remaining capture amount of ready_for_capture payments (only in manual capture mode). If you have not captured before, it equals a cancel of the payment. If you have captured partially before, the remaining amount will be freed and cannot be captured anymore.
Use the following endpoint:
bash
curl 'https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID/free_capture' \
--request POST \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.post(
"https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID/free_capture",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
}
)This will free the remaining capture amount of the payment. You will receive the updated payment object in the response. The payment will move into canceled state or paid state depending on whether you captured partially before or not.
Chargebacks
In case of a chargeback, the payment provider will notify the TiruPay Payment Processor via webhooks. The payment status will be updated to charged_back accordingly.
You can request all chargebacks of a payment via the following endpoint:
bash
curl 'https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID/chargebacks' \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.get(
"https://payments.sd-tirupay.de/payments/by_id/PAYMENT_ID/chargebacks",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
}
)You will receive a list of chargebacks in the response.
This is an example response:
json
[
{
"partner_id": "mollie_chargeback_12345",
"amount": 20.00,
"currency": "EUR",
"partner_payment_id": "mollue_payment_12345",
"created_at": "2024-01-01T12:00:00Z",
"partner_status": "NONE",
"chargeback_status": "won",
"reason": "Bank issued chargeback for unauthorized transaction"
}
]INFO
Mollie does not provide detailed chargeback statuses, so the partner_status field will always be NONE for Mollie chargebacks. Mollie provides if the chargeback was won or lost via the actual amount settled in the end. We use that to set the chargeback_status field accordingly.
Each chargeback includes details such as the amount, currency, and (optionally) reason for the chargeback. It will also include a chargeback_status field to indicate the current status of the chargeback:
open: The chargeback has been created but not yet processed.won: The chargeback has been resolved in favor of the merchant.lost: The chargeback has been resolved in favor of the customer.
If you want to inquire the exact status of the payment provider, look in the field partner_status.
WARNING
We do not automatically fetch chargeback updates and so we do not update the chargeback status automatically. You won't get notified about chargeback status changes via webhooks.
Fees
Concurrency
We fetch the transactions of a payment asynchronously. Therefore, fees might not be immediately available after payment completion.
Fees accumulate for the necessary transactions the payment provider needs to perform to process your payments (and related refunds, captures and chargebacks). To get the total amount of fees for a payment, iterate through it's transactions or call this endpoint:
bash
curl https://payment.sd-tirupay.de/payments/by_id/PAYMENT_ID/fees \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.get(
"https://payment.sd-tirupay.de/payments/by_id/PAYMENT_ID/fees",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
}
)This will return the total fees for the payment:
json
-10.35