Appearance
Connect / Partner OAuth Guide
How To Process Payments on behalf of Your Users Using Mollie / Stripe Connect and TiruPay Payment Processor.
Setup
You need to setup Apps in the Mollie and/or Stripe Dashboards to enable OAuth for your Partners.
Service Example
Given that you have setup the Apps in Mollie and/or Stripe, and implemented them in the TiruPay Payment Processor, your Partners can now connect their accounts to your service.
In the following:
- Partner: is the user of your service who wants to accept payments (e.g. Verein TSimon).
- Service: is your application that uses TiruPay Payment Processor to handle payments on behalf of your Partners (e.g. easyVerein).
- Customer: is the end-customer of your Partner who makes a payment (e.g. Max Mustermann) using the Service ( easyVerein).
- Partner Provider: is either Mollie or Stripe.
1. Setup an Partner OAuth Credentials object for your Partner.
This object holds all logic needed to connect the Partner to the Service via OAuth. For every request that shall be performed in the name of the Partner, you need to provide the partner_oauth_credentials_id in the request body.
bash
curl https://payments.sd-tirupay.de/partner_oauth/ \
--request POST \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY' \
--data '{
"user_name": "Partner TSimon",
"service_upi": "TSimon",
"service_id": "Service ID",
"partner": "mollie"
}'python
import requests
requests.post(
"https://payments.sd-tirupay.de/partner_oauth/",
headers={
"Accept": "*/*",
"Content-Type": "application/json",
"Authorization": "Bearer API_KEY"
},
json={
"user_name": "Partner TSimon",
"service_upi": "TSimon",
"service_id": "Service ID",
"partner": "mollie"
}
)Note that the service_upi is important. When creating a payment, this is the ID you need to send to select this Partner OAuth Credentials. The user_name is a human-readable identifier for you to identify the Partner later.
You will get an id in the response. Store this ID for the next step. We call this id our_id in the next steps.
2. Redirect your Partner to the Payment Provider to connect their account.
You have two possible options here:
Onboard them by providing additional data
If you know a lot about your customers and they DO NOT hold an account yet with the Partner Provider, you can provide additional data to onboard them directly.
bash
curl 'https://payments.sd-tirupay.de/partner_oauth/by_id/{our_id}/authorize_with_data?service_redirect_url=http%3A%2F%2Flocalhost%3A9000%2Ffinal_redirect&email=sb%40software-design.de&given_name=Max&family_name=Mustermann&organization_name=Acme%20Inc&address_street=Example%20Street%201&address_city=Freiburg&address_postal_code=79110&address_country_code=DE®istration_number=ABC12345678&vat_number=VAT12345678' \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.get(
"https://payments.sd-tirupay.de/partner_oauth/by_id/{our_id}/authorize_with_data",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
},
params={
"service_redirect_url": "http://localhost:9000/final_redirect",
"email": "sb@software-design.de",
"given_name": "Max",
"family_name": "Mustermann",
"organization_name": "Acme Inc",
"address_street": "Example Street 1",
"address_city": "Freiburg",
"address_postal_code": "79110",
"address_country_code": "DE",
"registration_number": "ABC12345678",
"vat_number": "VAT12345678"
}
)You will receive a URL in the response. Redirect your Partner to this URL to connect their account.
Let them fill out the data themselves
If your Partner already has an account with the Partner Provider, or you do not have enough data to onboard them directly, you can let them fill out the data themselves.
bash
curl 'https://payments.sd-tirupay.de/partner_oauth/by_id/{our_id}/authorize?service_redirect_url=http%3A%2Flocalhost%3A9000%2Ffinal_redirect' \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.get(
"https://payments.sd-tirupay.de/partner_oauth/by_id/{our_id}/authorize",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
},
params={
"service_redirect_url": "http:/localhost:9000/final_redirect"
}
)You will receive a URL in the response. Redirect your Partner to this URL to connect their account.
Mollie: Select a profile
Mollie allows users to have multiple profiles. You need to ensure your Partner has at least one (verified) profile in Mollie to be able to accept payments.
You can create new profiles using the /partner_oauth/by_id/{our_id}/profiles endpoint. You can list existing profiles using the /partner_oauth/by_id/{our_id}/profiles GET endpoint.
Once profiles exist, you can choose one using the following endpoint:
bash
curl 'https://payments.sd-tirupay.de/partner_oauth/by_id/{our_id}/profiles/{mollie_id}/choose' \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.post(
"https://payments.sd-tirupay.de/partner_oauth/by_id/{our_id}/profiles/{mollie_id}/choose",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
}
)Now you are ready to create payments on behalf of your Partner using the authenticated Partner OAuth Credentials.
3. Create Payments on behalf of your Partner
When creating a payment, provide the service_upi of the Partner OAuth Credentials you created in step 1 as partner_oauth_upi in the request body.
For this step, we assume the customer with the ID CUSTOMER_ID already exists on the TiruPay Payment Processor. See the customer example code for more information on this.
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 payment from TSimon",
"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",
"service_metadata": {
"propertyName*": "anything"
},
"partner_oauth_upi": "TSimon"
}'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 payment from TSimon",
"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",
"service_metadata": {
"propertyName*": "anything"
},
"partner_oauth_upi": "TSimon"
}
)This will return a payment object with an id. Store this ID for the next step.
4. Select Payment and Complete Checkout
Now that the payment is created, you can process as usual by selecting the payment and redirecting your Customer to the payment URL.
See the payment example code for more information on this.
Onboarding Status
We translate the onboarding status of the Partner Providers to a unified set of statuses. You can find the current onboarding status of your Partner by querying the Partner OAuth Credentials object. It's stored in the account_status field.
INFO
We fetch this status every 12 to 24 hours. If a change occured, we will inform you via webhook.
Possible statuses are:
restricted: The account is restricted/blocked/unavailable.needs_data: Additional data is required to complete the onboarding.needs_data_payments_available: Additional data is required, but payments can still be accepted.active: The account is fully verified and fully usable.
bash
curl 'https://payments.sd-tirupay.de/partner_oauth/by_id/{our_id}/' \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.get(
"https://payments.sd-tirupay.de/partner_oauth/by_id/{our_id}/",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
}
)Mollie: Get the current capabilities
The account status is mapped from the Mollie capabilities. You can also get the raw Mollie capabilities by querying the following endpoint:
bash
curl 'https://payments.sd-tirupay.de/partner_oauth/by_id/{our_id}/mollie/capabilities' \
--header 'Accept: */*' \
--header 'Authorization: Bearer API_KEY'python
import requests
requests.get(
"https://payments.sd-tirupay.de/partner_oauth/by_id/{our_id}/mollie/capabilities",
headers={
"Accept": "*/*",
"Authorization": "Bearer API_KEY"
}
)This will return the raw Mollie capabilities for the connected account.