Customer Registration

Versa routes receipts by matching against registered customers. Every time a sender (e.g. an airline, an E-commerce merchant) makes a sale, they check to see if one or more clients (e.g. an expense management app) are authorized to pull down receipts for that customer. For example: if Supplier A completes a sale to 'jshmoe@acme.com', and if Expense Management App B has registered as an authorized receiver of 'acme.com' receipts, then Versa will direct Supplier A to forward the encrypted receipt to Expense Management App B.

How It Works

Customers explicitly grant permission to senders or receivers to collect receipts on their behalf.

Registering and de-registering handles is typically performed via API. The Versa web app also includes a user interface to perform this action.

To register a handle via API:

curl --request POST \
  --url 'https://registry.versa.org/customer' \
  --header 'Authorization: Basic CLIENT_ID:CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "handle_type": "customer_email_domain",
    "handle": "acme.com"
  }'

Field	Type	Description
handle_type	enum	One of customer_email_domain (e.g. acme.com) or customer_email (e.g. jshmoe@acme.com).
handle	string	The handle value.
receiver_org_id	nullable string	The org id of the intended receiver. Required for any sender registration.

You’re responsible for collecting the necessary permission when registering customers. For customer_email registrations, the email addresses you add will also be subject to a verification step. When you initiate an email address registration, that registration will be put into a pending state. Versa sends a verification email to the address; you will start to receive matching receipts only after the recipient clicks the verification link contained in that email.

When you lose a customer, you will de-register them. To remove a registered profile:

curl --request DELETE \
  --url 'https://registry.versa.org/customer' \
  --header 'Authorization: Basic CLIENT_ID:CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "handle_type": "customer_email_domain",
    "handle": "acme.com"
  }'

Typically, you’ll do a batch registration when you initially onboard to Versa, and from that point forward, you’ll manage your list of authorized customers synchronously, registering and de-registering handles as you add and remove customers.

In 'test' mode, 'production' receipts will not be sent. Your client will need to be set to 'production' mode to send or receive production receipts. Contact Versa Support for details.

Receiver vs. Sender Customer Registration

Both receivers and senders can register customers, however these two types of registration have different scopes.

Receivers register customers to receive receipts from any sender. For example, when an expense management app gets permission from a customer to collect receipts on their behalf, they will receive receipts from all participating sender merchants.

Senders, on the other hand, can only register customers to receive the receipts from their direct sales. E.g. a travel manager admin who is logged in to the company settings screen on the 'Nimbus Airlines' website could opt to push their Nimbus Airlines receipts to their expense management app, but they would not be able to turn on universal receipt sync from within the Nimbus Airlines website.

Technically speaking, these receiver vs. sender registration scopes are configured via the receiver_org_id parameter on the /customer endpoint. Receiver clients do not need to specify a receiver_org_id — they can either skip the parameter, or set the value to their own org_id (anything else will error). Sender clients attempting to register customers must include a receiver_org_id, and that receiver_org_id must reference an active receiver client. If a sender client excludes the receiver_org_id parameter, the registration attempt will error.

Sender and receiver registrations are not mutually exclusive. For instance: if Sender A registers a customer for Receiver B, and Receiver B also registers that same customer, Versa will match against both registrations, and return a single reference to Receiver B.

Example Sender Registration Request

Below is an example curl request that registers the customer domain acme.com to send receipts to the Sandbox Firehose.

curl --request POST \
  --url 'https://registry.versa.org/customer' \
  --header 'Authorization: Basic CLIENT_ID:CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "handle_type": "customer_email_domain",
    "handle": "acme.com",
    "receiver_org_id": "org_2608b08d60f34075bbb36539883bb17f"
  }'

Sender Registration, "Merchant Group Codes", and "Merchant User Codes"

In addition to the standard domain and email -based forms of customer registration, senders can also register customers using a "merchant group code" (MGC) or a "merchant user code" (MUC).

A merchant group code is a unique identifer assigned to a corporate program. For example, a rental car company might have a 'corporate discount code' for Acme Co.

A merchant user code is a unique identifer assigned to an individual user. For example, an airline might have a loyalty program id for each of their frequent flyers.

'MGC' and 'MUC' handles give merchants the flexibility to register customers according to these core identifiers in their system, alongside more universal identifiers like domain and email.

Note: usage of 'MGC' and 'MUC' customer registration is currently invite-only. Contact Versa Support if you’d like to learn more about this feature.

Listing & Querying Receivers

If you are using sender registration, you can query our network of registered receivers using the Receiver Query API.