Connect a taxpayer

Stage 2 of 6. Connect each business before your app submits e-invoices with that business as the seller.

This page uses these terms:

• Your organization: the account of your company in the Wafeq ASP portal. Your company builds the app that uses the Wafeq ASP API. Your API keys, your OAuth client and your webhook endpoints belong to your organization.
• Business: a company that uses your app and wants to issue e-invoices with it.
• Grant: the permission that a business gives to your organization. A grant lets your app submit e-invoices in which that business is the seller.
• Taxpayer: a business from which your organization has an active grant. The API uses the Taxpayer ID (txpay_…) to identify it.

Two examples show how these terms fit together:

Example 1: a group of companies with its own ERP. A holding company builds an integration between its ERP and Wafeq ASP. The holding company creates one organization in the Wafeq ASP portal. Each company in the group has its own TIN. Each company onboards with Wafeq ASP and approves the integration. The organization of the holding company then has one grant from each company. In the API, each company is a separate taxpayer. The ERP submits the e-invoices of each company, with that company as the seller.

Example 2: a software company with many customers. A software company sells an invoicing app to other businesses. The software company creates one organization in the Wafeq ASP portal. Each customer that wants to issue e-invoices through the app onboards with Wafeq ASP and approves the app. The organization of the software company then has one grant from each of these customers. In the API, each customer is a taxpayer. The app submits the e-invoices of each customer, with that customer as the seller. A customer can revoke its grant at any time. After that, the app cannot submit e-invoices with that customer as the seller.

Your app can submit an e-invoice only if your organization has an active grant from the seller on the e-invoice. To give a grant, a business does two things:

1. Onboarding. The business appoints Wafeq ASP as its e-invoicing provider in EmaraTax. Wafeq ASP then registers the business with the FTA and on Peppol. A business does onboarding one time only, for all apps.
2. Approval. The business approves your app. This approval creates the grant.

The business does both things itself. Your app cannot do them for the business.

Your app starts this process with one OAuth 2.0 authorization flow. The flow takes the business through onboarding, if necessary, and then through approval. At the end of the flow, your app gets the Taxpayer ID and the grant ID.

Before you start

Do these tasks one time, in the Wafeq ASP portal:

1. Go to Developer → Settings.
2. Copy your OAuth client ID and client secret. Wafeq ASP shows the secret one time only.
3. Add your callback URLs (redirect URIs). You can add a maximum of 10 URLs. Each URL must use HTTPS. In Sandbox, http://localhost is also permitted.

Live and Sandbox have different OAuth clients. Use the client of the mode that you work in.

Limits in Live

In Live, Wafeq ASP checks three conditions when a new business approves your app. If a condition is not met, Wafeq ASP refuses the approval. The business sees an error on the approval page, and the error tells it to contact the support of your app. Thus, make sure that your organization meets these conditions before you send businesses to Wafeq ASP.

1. Your organization has an active subscription. The subscription is the paid plan of your organization for Wafeq ASP in Live. You buy and manage it in the Wafeq ASP portal. Without an active subscription, no business can approve your app in Live, and your app cannot submit e-invoices in Live.
2. Your subscription has a free taxpayer seat. Your subscription includes a number of taxpayer seats. Each seat holds one business. A business holds a seat while your organization has an active grant from it. When all seats are in use, a new business cannot approve your app. To free a seat, revoke all the grants of a business. To get more seats, change your subscription.
3. Your app is verified, or it has fewer than 25 businesses. Wafeq ASP verifies apps on request. An app that is not verified can have a maximum of 25 businesses in Live. To ask for verification, contact Wafeq ASP.

These conditions apply only to a business that is new to your organization. A business that already has an active grant for your organization holds a seat already. For example, a business can approve your app a second time, for a second workspace in your app. This gives your organization a second grant from the same business, but the business still holds only one seat.

A business that deregisters in EmaraTax keeps its seat until your organization revokes its grants.

In Sandbox, these conditions do not apply.

Connect a business: the five steps

You are now ready to connect a business. The connection has five steps. Your app does steps 1, 4 and 5. The business does steps 2 and 3.

The person who approves does not need an account in your app. For example, you can send the link to the owner of the business. For this reason, your callback must work with the authorization code and state only.

Optional check before step 1. Your app can check if a business is already onboarded with Wafeq ASP. Send POST /oauth/taxpayer-registration with the TIN of the business, and authenticate with your client ID and client secret. If the business is onboarded, taxpayer_registered is true, and the business does not do step 2. The response gives no other data about the business.

Step 1: Redirect the business to Wafeq ASP

Redirect the browser of the business to the authorization page of your mode:

Add these required parameters to the URL:

You can also add these optional parameters:

Example:

https://portal-einvoicing.wafeq.com/oauth/authorize?response_type=code
  &client_id=ocl_0123456789abcdef
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fwafeq%2Fcallback
  &scope=invoices%3Aread%20invoices%3Awrite%20inbound%3Aread
  &state=9f2c4e7a1b
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &tin_hint=1000001603
  &external_id=workspace-8812

Each time the business opens the link, Wafeq ASP starts a new request. The request stays valid for 2 hours. This gives a new business time to complete onboarding in EmaraTax.

Step 2: The business completes onboarding (new businesses only)

Only a business that is not onboarded with Wafeq ASP does this step. Your app has no part in this step.

The pages of Wafeq ASP tell the business to do these actions:

1. In EmaraTax, go to e-Invoicing and select Wafeq FZ LLC as the ASP.
2. Follow the link from EmaraTax back to Wafeq ASP.
3. Enter the TIN and the email address that are registered in EmaraTax.
4. Check the address of the business, with the emirate, and its legal registration.

Wafeq ASP then registers the business with the FTA and on Peppol. The page shows the progress.

A business that is already onboarded does not do this step. Instead, it signs in with a one-time link. Wafeq ASP sends this link to the email address that is registered in EmaraTax.

Step 3: The business approves your app

Wafeq ASP shows the approval page to the business. The page shows:

• The name, logo, website and support email of your app.
• The permissions that your app asks for.
• A warning, if the TIN of the business is different from your tin_hint. The business must accept the warning before it can continue.

If the business approves, Wafeq ASP creates the grant. At this time, Wafeq ASP also sends the taxpayer.created webhook to your organization.

If the business declines, Wafeq ASP redirects the business to your callback with error=access_denied. Wafeq ASP does not create a grant.

Step 4: Receive the callback and exchange the code

Wafeq ASP redirects the browser of the business to your callback URL. The URL contains two parameters:

• code: the authorization code.
• state: the value that you sent in step 1.

Do these actions on your server:

1. Compare state with the value that you kept in step 1. If the two values are different, stop.
2. Send the code to the token endpoint of your mode. Authenticate with your client ID and client secret (HTTP Basic).

curl https://portal-einvoicing.wafeq.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://app.example.com/wafeq/callback \
  -d code_verifier="$CODE_VERIFIER"

The code is valid for 10 minutes. You can exchange it one time only. If the exchange fails, do not try again with the same code. Start the flow again at step 1.

The response contains these fields:

Step 5: Check the result and store the IDs

Do these checks before you store the result:

1. Compare tin with the TIN that you expected. The tin_hint parameter only shows a warning. It does not stop the person from approving for a different business.
2. Make sure that scope contains all the permissions that your app needs.

If a check fails, revoke the grant with DELETE /grants/{grant_id}. Then start the flow again at step 1.

If the two checks pass, store taxpayer_id and grant_id with the account of the business in your app.

After the connection

The connection is complete after step 5. In the API, the business is now a taxpayer. The two sections below are not steps. They tell you how to use the connection and how to keep it up to date.

Call the API with the taxpayer as the seller

To submit an e-invoice with this taxpayer as the seller, send these headers:

Authorization: Api-Key pk_live_…
x-ae-taxpayer-id: txpay_…
x-ae-grant-id: tgr_…

• Authorization contains the API key of your organization.
• x-ae-taxpayer-id identifies the taxpayer.
• x-ae-grant-id identifies the grant. If the business revokes the grant, Wafeq ASP refuses the call immediately.

With this method, your app does not store or refresh tokens. For other methods, refer to Authentication. For the steps to submit an e-invoice, refer to Submit a document.

Keep the connection up to date

Wafeq ASP sends these webhooks to your organization:

When your app receives one of these webhooks, read GET /grants and GET /taxpayers to get the current state.

These events change a connection:

• The business revokes the grant. The business can do this at any time, in its Wafeq ASP workspace, under Connected apps.
• Your app revokes the grant. Send DELETE /grants/{grant_id}. When your organization has no more active grants from the taxpayer, its seat becomes free. The business stays onboarded with Wafeq ASP.
• The business connects again. Start the flow again at step 1. If you send the same external_id, the new grant replaces the old grant.
• The business deregisters in EmaraTax. Your app can no longer submit e-invoices with this taxpayer as the seller. Your app can still read the documents of the taxpayer. The taxpayer holds its seat until your organization revokes its grants.

Connections in Sandbox

In Sandbox, the business does not go to EmaraTax. Wafeq ASP simulates the onboarding. Refer to Sandbox.

Next

Stage 3: Submit a document.